@sdflc/backend-helpers 1.0.139 → 1.0.141
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +471 -29
- package/build/EmergencyAlerter.d.ts +140 -0
- package/build/EmergencyAlerter.js +465 -0
- package/build/esm/EmergencyAlerter.d.ts +140 -0
- package/build/esm/EmergencyAlerter.js +454 -0
- package/build/esm/gateways/BaseExternalApiGateway.d.ts +94 -0
- package/build/esm/gateways/BaseExternalApiGateway.js +319 -0
- package/build/esm/gateways/DiscordWebhookGw.d.ts +50 -0
- package/build/esm/gateways/DiscordWebhookGw.js +70 -0
- package/build/esm/gateways/HttpWebhookGw.d.ts +43 -0
- package/build/esm/gateways/HttpWebhookGw.js +131 -0
- package/build/esm/gateways/SendGridGw.d.ts +41 -0
- package/build/esm/gateways/SendGridGw.js +116 -0
- package/build/esm/gateways/SlackWebhookGw.d.ts +23 -0
- package/build/esm/gateways/SlackWebhookGw.js +59 -0
- package/build/esm/gateways/TelegramGw.d.ts +45 -0
- package/build/esm/gateways/TelegramGw.js +110 -0
- package/build/esm/gateways/TwilioGw.d.ts +33 -0
- package/build/esm/gateways/TwilioGw.js +107 -0
- package/build/esm/gateways/externalUrl.d.ts +16 -0
- package/build/esm/gateways/externalUrl.js +116 -0
- package/build/esm/gateways/guardedFetch.d.ts +15 -0
- package/build/esm/gateways/guardedFetch.js +133 -0
- package/build/esm/gateways/index.d.ts +9 -0
- package/build/esm/gateways/index.js +9 -0
- package/build/esm/index.d.ts +2 -1
- package/build/esm/index.js +2 -1
- package/build/esm/interfaces/BaseExternalApiGatewayPropsInterface.d.ts +16 -2
- package/build/gateways/BaseExternalApiGateway.d.ts +94 -0
- package/build/gateways/BaseExternalApiGateway.js +326 -0
- package/build/gateways/DiscordWebhookGw.d.ts +50 -0
- package/build/gateways/DiscordWebhookGw.js +73 -0
- package/build/gateways/HttpWebhookGw.d.ts +43 -0
- package/build/gateways/HttpWebhookGw.js +135 -0
- package/build/gateways/SendGridGw.d.ts +41 -0
- package/build/gateways/SendGridGw.js +119 -0
- package/build/gateways/SlackWebhookGw.d.ts +23 -0
- package/build/gateways/SlackWebhookGw.js +62 -0
- package/build/gateways/TelegramGw.d.ts +45 -0
- package/build/gateways/TelegramGw.js +115 -0
- package/build/gateways/TwilioGw.d.ts +33 -0
- package/build/gateways/TwilioGw.js +110 -0
- package/build/gateways/externalUrl.d.ts +16 -0
- package/build/gateways/externalUrl.js +121 -0
- package/build/gateways/guardedFetch.d.ts +15 -0
- package/build/gateways/guardedFetch.js +141 -0
- package/build/gateways/index.d.ts +9 -0
- package/build/gateways/index.js +25 -0
- package/build/index.d.ts +2 -1
- package/build/index.js +2 -1
- package/build/interfaces/BaseExternalApiGatewayPropsInterface.d.ts +16 -2
- package/package.json +2 -1
- package/build/BaseExternalApiGateway.d.ts +0 -16
- package/build/BaseExternalApiGateway.js +0 -54
- package/build/esm/BaseExternalApiGateway.d.ts +0 -16
- package/build/esm/BaseExternalApiGateway.js +0 -48
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
// ./src/gateways/TwilioGw.ts
|
|
2
|
+
//
|
|
3
|
+
// Sends SMS (and WhatsApp, with `whatsapp:` addresses) through Twilio's Messages API
|
|
4
|
+
// (POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages.json). No SDK: one REST call.
|
|
5
|
+
//
|
|
6
|
+
// const twilio = new TwilioGw().configure({ accountSid, authToken, from: '+15551234567' });
|
|
7
|
+
// const result = await twilio.sendMessage({ to: '+15557654321', body: 'Hello' });
|
|
8
|
+
//
|
|
9
|
+
// ⚠ The auth token is scrubbed out of every error this returns.
|
|
10
|
+
import { Buffer } from 'buffer';
|
|
11
|
+
import { OP_RESULT_CODES, OpResult } from '@sdflc/api-helpers';
|
|
12
|
+
import { BaseExternalApiGateway } from './BaseExternalApiGateway';
|
|
13
|
+
const TWILIO_BASE_URL = 'https://api.twilio.com';
|
|
14
|
+
const ACCOUNT_SID_FORMAT = /^AC[0-9a-fA-F]{32}$/;
|
|
15
|
+
const ADDRESS_FORMAT = /^(whatsapp:)?\+[1-9]\d{6,14}$/;
|
|
16
|
+
/** Twilio's limit on one message body. */
|
|
17
|
+
export const TWILIO_MAX_BODY_LENGTH = 1600;
|
|
18
|
+
class TwilioGw extends BaseExternalApiGateway {
|
|
19
|
+
constructor(props) {
|
|
20
|
+
super({ baseUrl: TWILIO_BASE_URL, ...(props ?? {}) });
|
|
21
|
+
}
|
|
22
|
+
validateSettings(settings) {
|
|
23
|
+
const problems = [];
|
|
24
|
+
if (!ACCOUNT_SID_FORMAT.test(String(settings.accountSid ?? '').trim())) {
|
|
25
|
+
problems.push('the account SID is missing or malformed (AC + 32 hex characters)');
|
|
26
|
+
}
|
|
27
|
+
if (!String(settings.authToken ?? '').trim()) {
|
|
28
|
+
problems.push('the auth token is missing');
|
|
29
|
+
}
|
|
30
|
+
if (settings.from && !ADDRESS_FORMAT.test(String(settings.from).trim())) {
|
|
31
|
+
problems.push('the From number is not E.164 (+15551234567, or whatsapp:+15551234567)');
|
|
32
|
+
}
|
|
33
|
+
return problems;
|
|
34
|
+
}
|
|
35
|
+
secretValues() {
|
|
36
|
+
const sid = String(this.settings.accountSid ?? '').trim();
|
|
37
|
+
const token = String(this.settings.authToken ?? '').trim();
|
|
38
|
+
return [token, Buffer.from(`${sid}:${token}`).toString('base64')];
|
|
39
|
+
}
|
|
40
|
+
/** ⚠ Not after a TIMEOUT: Twilio may well have accepted the message, and a retry texts the person twice. */
|
|
41
|
+
shouldRetry(result) {
|
|
42
|
+
return result.getCode() !== OP_RESULT_CODES.TIMEOUT && super.shouldRetry(result);
|
|
43
|
+
}
|
|
44
|
+
errorMessageOf(reply) {
|
|
45
|
+
const body = reply.body;
|
|
46
|
+
if (body && typeof body === 'object' && body.message) {
|
|
47
|
+
return `${body.message}${body.code ? ` (Twilio ${body.code})` : ''}`.slice(0, 500);
|
|
48
|
+
}
|
|
49
|
+
return super.errorMessageOf(reply);
|
|
50
|
+
}
|
|
51
|
+
/** Sends one message. OK with `{ sid, status }`. Never throws. */
|
|
52
|
+
async sendMessage(message) {
|
|
53
|
+
if (!this.isConfigured()) {
|
|
54
|
+
return this.notConfigured();
|
|
55
|
+
}
|
|
56
|
+
const to = String(message?.to ?? '').trim();
|
|
57
|
+
const from = String(message?.from ?? this.settings.from ?? '').trim();
|
|
58
|
+
const body = String(message?.body ?? '');
|
|
59
|
+
const problems = [];
|
|
60
|
+
if (!ADDRESS_FORMAT.test(to)) {
|
|
61
|
+
problems.push('the recipient is not E.164 (+15557654321, or whatsapp:+15557654321)');
|
|
62
|
+
}
|
|
63
|
+
if (!from && !this.settings.messagingServiceSid) {
|
|
64
|
+
problems.push('there is no sender (configure from or messagingServiceSid, or pass from)');
|
|
65
|
+
}
|
|
66
|
+
if (from && !ADDRESS_FORMAT.test(from)) {
|
|
67
|
+
problems.push('the sender is not E.164');
|
|
68
|
+
}
|
|
69
|
+
if (!body) {
|
|
70
|
+
problems.push('the message is empty');
|
|
71
|
+
}
|
|
72
|
+
else if (body.length > TWILIO_MAX_BODY_LENGTH) {
|
|
73
|
+
problems.push(`the message is ${body.length} characters; Twilio allows ${TWILIO_MAX_BODY_LENGTH}`);
|
|
74
|
+
}
|
|
75
|
+
if (problems.length) {
|
|
76
|
+
return OpResult.fail(OP_RESULT_CODES.VALIDATION_FAILED, null, `The message cannot be sent: ${problems.join('; ')}`);
|
|
77
|
+
}
|
|
78
|
+
const form = new URLSearchParams();
|
|
79
|
+
form.set('To', to);
|
|
80
|
+
form.set('Body', body);
|
|
81
|
+
if (from) {
|
|
82
|
+
form.set('From', from);
|
|
83
|
+
}
|
|
84
|
+
else {
|
|
85
|
+
form.set('MessagingServiceSid', String(this.settings.messagingServiceSid));
|
|
86
|
+
}
|
|
87
|
+
if (message.statusCallback) {
|
|
88
|
+
form.set('StatusCallback', message.statusCallback);
|
|
89
|
+
}
|
|
90
|
+
for (const url of message.mediaUrl ?? []) {
|
|
91
|
+
form.append('MediaUrl', url);
|
|
92
|
+
}
|
|
93
|
+
const sid = String(this.settings.accountSid).trim();
|
|
94
|
+
const auth = Buffer.from(`${sid}:${String(this.settings.authToken).trim()}`).toString('base64');
|
|
95
|
+
const result = await this.requestWithRetries({
|
|
96
|
+
url: `${this.baseUrl}/2010-04-01/Accounts/${sid}/Messages.json`,
|
|
97
|
+
headers: { Authorization: `Basic ${auth}`, 'Content-Type': 'application/x-www-form-urlencoded' },
|
|
98
|
+
body: form,
|
|
99
|
+
});
|
|
100
|
+
if (result.didFail()) {
|
|
101
|
+
return result;
|
|
102
|
+
}
|
|
103
|
+
const reply = result.getDataFirst()?.body;
|
|
104
|
+
return OpResult.ok([{ sid: reply?.sid ?? null, status: reply?.status ?? null }]);
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
export { TwilioGw };
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import { OpResult } from '@sdflc/api-helpers';
|
|
2
|
+
/** True when an IP address is one a user-given URL must never reach. Pure. */
|
|
3
|
+
export declare const isBlockedAddress: (address: string) => boolean;
|
|
4
|
+
export interface ExternalUrlOptions {
|
|
5
|
+
/** Default ['https:', 'http:']. */
|
|
6
|
+
protocols?: string[];
|
|
7
|
+
/** Resolves a hostname to every address (tests pass their own). Default: the system resolver. */
|
|
8
|
+
lookup?: (hostname: string) => Promise<string[]>;
|
|
9
|
+
/** The field the error is reported under. Default '' (a general error, like every other gateway refusal). */
|
|
10
|
+
field?: string;
|
|
11
|
+
}
|
|
12
|
+
/**
|
|
13
|
+
* OK when `url` may be requested: a permitted protocol, no credentials in it, and a host that is not — and does not
|
|
14
|
+
* resolve to — a local, private or reserved address. Else VALIDATION_FAILED, saying why. Never throws.
|
|
15
|
+
*/
|
|
16
|
+
export declare const checkExternalUrl: (url: string, opts?: ExternalUrlOptions) => Promise<OpResult>;
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
// ./src/gateways/externalUrl.ts
|
|
2
|
+
//
|
|
3
|
+
// Is this URL safe to send a request to on someone else's say-so? A URL a USER typed (a webhook) must not reach our own
|
|
4
|
+
// network: localhost, the private ranges, the cloud metadata service (169.254.169.254 hands out credentials), or any of
|
|
5
|
+
// them spelled another way (an IPv4 address written as IPv6, a hostname that resolves to one).
|
|
6
|
+
//
|
|
7
|
+
// ⚠ EVERY address a hostname resolves to is checked — a name with one public and one private address is refused.
|
|
8
|
+
// ⚠ What it cannot stop alone: a hostname that resolves to a public address now and a private one at the moment of the
|
|
9
|
+
// request (DNS rebinding). Gateways that use this also refuse to follow redirects; together that narrows it to a
|
|
10
|
+
// window of milliseconds, not closes it.
|
|
11
|
+
import { BlockList, isIP } from 'net';
|
|
12
|
+
import { promises as dns } from 'dns';
|
|
13
|
+
import { OP_RESULT_CODES, OpResult } from '@sdflc/api-helpers';
|
|
14
|
+
const BLOCKED = new BlockList();
|
|
15
|
+
// IPv4: "this network", private, carrier-grade NAT, loopback, link-local (metadata), protocol assignments, test nets,
|
|
16
|
+
// benchmarking, multicast, reserved, broadcast.
|
|
17
|
+
for (const [network, prefix] of [
|
|
18
|
+
['0.0.0.0', 8],
|
|
19
|
+
['10.0.0.0', 8],
|
|
20
|
+
['100.64.0.0', 10],
|
|
21
|
+
['127.0.0.0', 8],
|
|
22
|
+
['169.254.0.0', 16],
|
|
23
|
+
['172.16.0.0', 12],
|
|
24
|
+
['192.0.0.0', 24],
|
|
25
|
+
['192.0.2.0', 24],
|
|
26
|
+
['192.168.0.0', 16],
|
|
27
|
+
['198.18.0.0', 15],
|
|
28
|
+
['192.88.99.0', 24],
|
|
29
|
+
['198.51.100.0', 24],
|
|
30
|
+
['203.0.113.0', 24],
|
|
31
|
+
['224.0.0.0', 4],
|
|
32
|
+
['240.0.0.0', 4],
|
|
33
|
+
]) {
|
|
34
|
+
BLOCKED.addSubnet(network, prefix, 'ipv4');
|
|
35
|
+
}
|
|
36
|
+
// IPv6: unspecified, loopback, IPv4-compatible (`::127.0.0.1`), NAT64 — both prefixes — and 6to4 (all reach IPv4
|
|
37
|
+
// inside), discard-only, documentation, unique-local (fc00::/7 = fc… AND fd…), link-local, multicast.
|
|
38
|
+
// ⓘ IPv4-MAPPED (`::ffff:127.0.0.1`) needs no rule of its own: BlockList checks it against the IPv4 rules.
|
|
39
|
+
for (const [network, prefix] of [
|
|
40
|
+
['::', 128],
|
|
41
|
+
['::1', 128],
|
|
42
|
+
['::', 96],
|
|
43
|
+
['64:ff9b::', 96],
|
|
44
|
+
['64:ff9b:1::', 48],
|
|
45
|
+
['100::', 64],
|
|
46
|
+
['2002::', 16],
|
|
47
|
+
['2001:db8::', 32],
|
|
48
|
+
['fc00::', 7],
|
|
49
|
+
['fe80::', 10],
|
|
50
|
+
['ff00::', 8],
|
|
51
|
+
]) {
|
|
52
|
+
BLOCKED.addSubnet(network, prefix, 'ipv6');
|
|
53
|
+
}
|
|
54
|
+
const BLOCKED_HOSTNAMES = new Set(['localhost', 'localhost.localdomain', 'metadata', 'metadata.google.internal']);
|
|
55
|
+
/** True when an IP address is one a user-given URL must never reach. Pure. */
|
|
56
|
+
export const isBlockedAddress = (address) => {
|
|
57
|
+
const ip = String(address ?? '')
|
|
58
|
+
.replace(/^\[|\]$/g, '')
|
|
59
|
+
.split('%')[0];
|
|
60
|
+
const version = isIP(ip);
|
|
61
|
+
if (version === 4) {
|
|
62
|
+
return BLOCKED.check(ip, 'ipv4');
|
|
63
|
+
}
|
|
64
|
+
if (version === 6) {
|
|
65
|
+
// ⓘ BlockList matches an IPv4-MAPPED address (`::ffff:127.0.0.1`, `::ffff:7f00:1`) against the IPv4 rules itself.
|
|
66
|
+
return BLOCKED.check(ip, 'ipv6');
|
|
67
|
+
}
|
|
68
|
+
// Not an address at all: refuse rather than guess.
|
|
69
|
+
return true;
|
|
70
|
+
};
|
|
71
|
+
const systemLookup = async (hostname) => (await dns.lookup(hostname, { all: true, verbatim: true })).map((one) => one.address);
|
|
72
|
+
/**
|
|
73
|
+
* OK when `url` may be requested: a permitted protocol, no credentials in it, and a host that is not — and does not
|
|
74
|
+
* resolve to — a local, private or reserved address. Else VALIDATION_FAILED, saying why. Never throws.
|
|
75
|
+
*/
|
|
76
|
+
export const checkExternalUrl = async (url, opts = {}) => {
|
|
77
|
+
const field = opts.field ?? '';
|
|
78
|
+
const refuse = (why) => OpResult.fail(OP_RESULT_CODES.VALIDATION_FAILED, null, { [field]: why });
|
|
79
|
+
let parsed;
|
|
80
|
+
try {
|
|
81
|
+
parsed = new URL(String(url ?? '').trim());
|
|
82
|
+
}
|
|
83
|
+
catch {
|
|
84
|
+
return refuse('The URL is not valid');
|
|
85
|
+
}
|
|
86
|
+
if (!(opts.protocols ?? ['https:', 'http:']).includes(parsed.protocol)) {
|
|
87
|
+
return refuse(`Only ${(opts.protocols ?? ['https:', 'http:']).join(' and ')} URLs are allowed`);
|
|
88
|
+
}
|
|
89
|
+
if (parsed.username || parsed.password) {
|
|
90
|
+
return refuse('A URL must not carry a user name or password');
|
|
91
|
+
}
|
|
92
|
+
const host = parsed.hostname
|
|
93
|
+
.toLowerCase()
|
|
94
|
+
.replace(/^\[|\]$/g, '')
|
|
95
|
+
.replace(/\.$/, '');
|
|
96
|
+
if (!host || BLOCKED_HOSTNAMES.has(host) || host.endsWith('.localhost') || host.endsWith('.internal')) {
|
|
97
|
+
return refuse('This host is not allowed');
|
|
98
|
+
}
|
|
99
|
+
if (isIP(host)) {
|
|
100
|
+
return isBlockedAddress(host) ? refuse('This address is not allowed') : OpResult.ok([]);
|
|
101
|
+
}
|
|
102
|
+
let addresses;
|
|
103
|
+
try {
|
|
104
|
+
addresses = await (opts.lookup ?? systemLookup)(host);
|
|
105
|
+
}
|
|
106
|
+
catch {
|
|
107
|
+
return refuse('The host name does not resolve');
|
|
108
|
+
}
|
|
109
|
+
if (!addresses.length) {
|
|
110
|
+
return refuse('The host name does not resolve');
|
|
111
|
+
}
|
|
112
|
+
// ⚠ EVERY address: a name with one public and one private address is refused.
|
|
113
|
+
return addresses.some(isBlockedAddress)
|
|
114
|
+
? refuse('The host name resolves to an address that is not allowed')
|
|
115
|
+
: OpResult.ok([]);
|
|
116
|
+
};
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
import { lookup as dnsLookup } from 'dns';
|
|
2
|
+
import { ExternalApiFetch } from '../interfaces';
|
|
3
|
+
export interface GuardedFetchOptions {
|
|
4
|
+
/** The resolver (dns.lookup's shape) — tests pass their own. */
|
|
5
|
+
dnsLookup?: typeof dnsLookup;
|
|
6
|
+
/** Which addresses are refused. Default `isBlockedAddress`. */
|
|
7
|
+
isBlocked?: (address: string) => boolean;
|
|
8
|
+
}
|
|
9
|
+
/**
|
|
10
|
+
* A `dns.lookup` that refuses when ANY address the name resolves to is blocked (a name with one private address among
|
|
11
|
+
* public ones is refused, whichever the socket would have picked).
|
|
12
|
+
*/
|
|
13
|
+
export declare const guardedLookup: (opts?: GuardedFetchOptions) => (hostname: string, options: any, callback: (...args: any[]) => void) => void;
|
|
14
|
+
/** A fetch whose every connection goes through `guardedLookup`. The answer has `status`, `headers` and `text()`. */
|
|
15
|
+
export declare const createGuardedFetch: (opts?: GuardedFetchOptions) => ExternalApiFetch;
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
// ./src/gateways/guardedFetch.ts
|
|
2
|
+
//
|
|
3
|
+
// A `fetch` for URLs a USER gave us (webhooks) that refuses a forbidden address AT THE MOMENT OF CONNECTING.
|
|
4
|
+
//
|
|
5
|
+
// ⚠ WHY NOT JUST CHECK THE URL FIRST: `checkExternalUrl` resolves the host name once; the platform fetch then resolves it
|
|
6
|
+
// AGAIN, on every attempt. A DNS server that answers a public address to the first lookup and 169.254.169.254 to the
|
|
7
|
+
// second (DNS rebinding) walks straight past a check made beforehand. Here the address the socket actually connects
|
|
8
|
+
// to is the one checked: Node's `http(s).request` takes the lookup, and this lookup refuses a blocked address.
|
|
9
|
+
// ⚠ An IP written in the URL is never looked up — it is checked here directly.
|
|
10
|
+
// ⚠ Redirects are never followed (http.request does not), the reply is capped at MAX_REPLY_BYTES, and the request ends at
|
|
11
|
+
// its signal (the gateway's timeout).
|
|
12
|
+
import http from 'http';
|
|
13
|
+
import https from 'https';
|
|
14
|
+
import { Buffer } from 'buffer';
|
|
15
|
+
import { isIP } from 'net';
|
|
16
|
+
import { lookup as dnsLookup } from 'dns';
|
|
17
|
+
import { MAX_REPLY_BYTES } from './BaseExternalApiGateway';
|
|
18
|
+
import { isBlockedAddress } from './externalUrl';
|
|
19
|
+
/** The error a refused address raises — the gateway reports it as VALIDATION_FAILED, never retried. */
|
|
20
|
+
const blockedError = (address) => Object.assign(new Error(`The address ${address} is not allowed`), { code: 'EBLOCKED' });
|
|
21
|
+
/**
|
|
22
|
+
* A `dns.lookup` that refuses when ANY address the name resolves to is blocked (a name with one private address among
|
|
23
|
+
* public ones is refused, whichever the socket would have picked).
|
|
24
|
+
*/
|
|
25
|
+
export const guardedLookup = (opts = {}) => (hostname, options, callback) => {
|
|
26
|
+
const resolve = opts.dnsLookup ?? dnsLookup;
|
|
27
|
+
const isBlocked = opts.isBlocked ?? isBlockedAddress;
|
|
28
|
+
const wantsAll = typeof options === 'object' && options?.all === true;
|
|
29
|
+
resolve(hostname, { ...(typeof options === 'object' ? options : {}), all: true }, (err, addresses) => {
|
|
30
|
+
if (err) {
|
|
31
|
+
callback(err);
|
|
32
|
+
return;
|
|
33
|
+
}
|
|
34
|
+
const list = Array.isArray(addresses) ? addresses : [];
|
|
35
|
+
const refused = list.find((one) => isBlocked(String(one?.address)));
|
|
36
|
+
if (refused || list.length === 0) {
|
|
37
|
+
callback(refused
|
|
38
|
+
? blockedError(String(refused.address))
|
|
39
|
+
: Object.assign(new Error(`${hostname} did not resolve`), { code: 'ENOTFOUND' }));
|
|
40
|
+
return;
|
|
41
|
+
}
|
|
42
|
+
if (wantsAll) {
|
|
43
|
+
callback(null, list);
|
|
44
|
+
}
|
|
45
|
+
else {
|
|
46
|
+
callback(null, list[0].address, list[0].family);
|
|
47
|
+
}
|
|
48
|
+
});
|
|
49
|
+
};
|
|
50
|
+
/** A fetch whose every connection goes through `guardedLookup`. The answer has `status`, `headers` and `text()`. */
|
|
51
|
+
export const createGuardedFetch = (opts = {}) => {
|
|
52
|
+
const isBlocked = opts.isBlocked ?? isBlockedAddress;
|
|
53
|
+
return (url, init = {}) => new Promise((resolve, reject) => {
|
|
54
|
+
let target;
|
|
55
|
+
try {
|
|
56
|
+
target = new URL(url);
|
|
57
|
+
}
|
|
58
|
+
catch {
|
|
59
|
+
reject(new TypeError('Invalid URL'));
|
|
60
|
+
return;
|
|
61
|
+
}
|
|
62
|
+
const literal = target.hostname.replace(/^\[|\]$/g, '');
|
|
63
|
+
if (isIP(literal) && isBlocked(literal)) {
|
|
64
|
+
reject(blockedError(literal));
|
|
65
|
+
return;
|
|
66
|
+
}
|
|
67
|
+
const signal = init.signal;
|
|
68
|
+
if (signal?.aborted) {
|
|
69
|
+
reject(signal.reason);
|
|
70
|
+
return;
|
|
71
|
+
}
|
|
72
|
+
const transport = target.protocol === 'https:' ? https : target.protocol === 'http:' ? http : null;
|
|
73
|
+
if (!transport) {
|
|
74
|
+
reject(new TypeError(`Unsupported protocol ${target.protocol}`));
|
|
75
|
+
return;
|
|
76
|
+
}
|
|
77
|
+
let req;
|
|
78
|
+
try {
|
|
79
|
+
req = transport.request(target, {
|
|
80
|
+
method: init.method ?? 'GET',
|
|
81
|
+
headers: init.headers ?? {},
|
|
82
|
+
lookup: guardedLookup(opts),
|
|
83
|
+
});
|
|
84
|
+
}
|
|
85
|
+
catch (e) {
|
|
86
|
+
// A malformed header is refused synchronously.
|
|
87
|
+
reject(e instanceof TypeError ? e : new TypeError(String(e?.message ?? e)));
|
|
88
|
+
return;
|
|
89
|
+
}
|
|
90
|
+
const onAbort = () => req.destroy(signal?.reason);
|
|
91
|
+
signal?.addEventListener('abort', onAbort, { once: true });
|
|
92
|
+
req.on('error', (e) => {
|
|
93
|
+
signal?.removeEventListener('abort', onAbort);
|
|
94
|
+
reject(e);
|
|
95
|
+
});
|
|
96
|
+
req.on('response', (res) => {
|
|
97
|
+
const chunks = [];
|
|
98
|
+
let size = 0;
|
|
99
|
+
let settled = false;
|
|
100
|
+
const finish = () => {
|
|
101
|
+
if (settled) {
|
|
102
|
+
return;
|
|
103
|
+
}
|
|
104
|
+
settled = true;
|
|
105
|
+
signal?.removeEventListener('abort', onAbort);
|
|
106
|
+
const text = Buffer.concat(chunks).toString('utf8');
|
|
107
|
+
resolve({ status: res.statusCode ?? 0, headers: { ...res.headers }, text: async () => text });
|
|
108
|
+
};
|
|
109
|
+
res.on('data', (chunk) => {
|
|
110
|
+
if (size + chunk.length > MAX_REPLY_BYTES) {
|
|
111
|
+
chunks.push(chunk.subarray(0, MAX_REPLY_BYTES - size));
|
|
112
|
+
size = MAX_REPLY_BYTES;
|
|
113
|
+
finish();
|
|
114
|
+
res.destroy();
|
|
115
|
+
return;
|
|
116
|
+
}
|
|
117
|
+
chunks.push(chunk);
|
|
118
|
+
size += chunk.length;
|
|
119
|
+
});
|
|
120
|
+
res.on('end', finish);
|
|
121
|
+
res.on('error', (e) => {
|
|
122
|
+
if (!settled) {
|
|
123
|
+
settled = true;
|
|
124
|
+
reject(e);
|
|
125
|
+
}
|
|
126
|
+
});
|
|
127
|
+
});
|
|
128
|
+
if (init.body !== undefined && init.body !== null) {
|
|
129
|
+
req.write(typeof init.body === 'string' ? init.body : String(init.body));
|
|
130
|
+
}
|
|
131
|
+
req.end();
|
|
132
|
+
});
|
|
133
|
+
};
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
export * from './BaseExternalApiGateway';
|
|
2
|
+
export * from './externalUrl';
|
|
3
|
+
export * from './SendGridGw';
|
|
4
|
+
export * from './TelegramGw';
|
|
5
|
+
export * from './TwilioGw';
|
|
6
|
+
export * from './SlackWebhookGw';
|
|
7
|
+
export * from './DiscordWebhookGw';
|
|
8
|
+
export * from './HttpWebhookGw';
|
|
9
|
+
export * from './guardedFetch';
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
export * from './BaseExternalApiGateway';
|
|
2
|
+
export * from './externalUrl';
|
|
3
|
+
export * from './SendGridGw';
|
|
4
|
+
export * from './TelegramGw';
|
|
5
|
+
export * from './TwilioGw';
|
|
6
|
+
export * from './SlackWebhookGw';
|
|
7
|
+
export * from './DiscordWebhookGw';
|
|
8
|
+
export * from './HttpWebhookGw';
|
|
9
|
+
export * from './guardedFetch';
|
package/build/esm/index.d.ts
CHANGED
|
@@ -21,6 +21,7 @@ export * from './commonValidators';
|
|
|
21
21
|
export * from './downloadHelpers';
|
|
22
22
|
export * from './resolveClientIp';
|
|
23
23
|
export * from './BaseRestApiCrudController';
|
|
24
|
-
export * from './
|
|
24
|
+
export * from './gateways';
|
|
25
25
|
export * from './IpRateLimiter';
|
|
26
26
|
export * from './uuidHelpers';
|
|
27
|
+
export * from './EmergencyAlerter';
|
package/build/esm/index.js
CHANGED
|
@@ -21,6 +21,7 @@ export * from './commonValidators';
|
|
|
21
21
|
export * from './downloadHelpers';
|
|
22
22
|
export * from './resolveClientIp';
|
|
23
23
|
export * from './BaseRestApiCrudController';
|
|
24
|
-
export * from './
|
|
24
|
+
export * from './gateways';
|
|
25
25
|
export * from './IpRateLimiter';
|
|
26
26
|
export * from './uuidHelpers';
|
|
27
|
+
export * from './EmergencyAlerter';
|
|
@@ -1,8 +1,16 @@
|
|
|
1
|
-
|
|
1
|
+
/** The HTTP client a gateway calls — the platform `fetch` unless a test passes its own. */
|
|
2
|
+
export type ExternalApiFetch = (url: string, init: any) => Promise<any>;
|
|
3
|
+
export interface BaseExternalApiGatewayPropsInterface<TSettings extends Record<string, any> = Record<string, any>> {
|
|
4
|
+
/**
|
|
5
|
+
* Optional settings to start with — the same as calling `configure(settings)` right after construction.
|
|
6
|
+
* A gateway is usually created ONCE and configured (and re-configured) at run time.
|
|
7
|
+
*/
|
|
8
|
+
settings?: TSettings;
|
|
2
9
|
/**
|
|
3
10
|
* Optional credentials — a plain API key string or a structured object
|
|
4
11
|
* with whatever keys the external service requires.
|
|
5
12
|
* Can also be set later via setCredentials() once resolved at runtime.
|
|
13
|
+
* ⓘ Kept for gateways written before `configure()`; a new gateway takes its credentials in its settings.
|
|
6
14
|
*/
|
|
7
15
|
credentials?: string | Record<string, any>;
|
|
8
16
|
/**
|
|
@@ -11,9 +19,15 @@ export interface BaseExternalApiGatewayPropsInterface {
|
|
|
11
19
|
*/
|
|
12
20
|
baseUrl?: string;
|
|
13
21
|
/**
|
|
14
|
-
* Timeout in milliseconds for outbound
|
|
22
|
+
* Timeout in milliseconds for one outbound request.
|
|
15
23
|
* Defaults to 10000.
|
|
16
24
|
*/
|
|
17
25
|
timeoutMs?: number;
|
|
26
|
+
/** Attempts AFTER the first one, for failures worth retrying (network, timeout, 429, 5xx). Defaults to 2. */
|
|
27
|
+
retries?: number;
|
|
28
|
+
/** The waits between attempts, in milliseconds (the last one repeats). Defaults to [1000, 2000]. */
|
|
29
|
+
retryDelaysMs?: number[];
|
|
30
|
+
/** The HTTP client. Defaults to the platform `fetch`. */
|
|
31
|
+
fetch?: ExternalApiFetch;
|
|
18
32
|
logger?: any;
|
|
19
33
|
}
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
import { OpResult } from '@sdflc/api-helpers';
|
|
2
|
+
import { Logger } from '@sdflc/utils';
|
|
3
|
+
import { BaseExternalApiGatewayPropsInterface, ExternalApiFetch } from '../interfaces';
|
|
4
|
+
/** One outbound HTTP request. */
|
|
5
|
+
export interface ExternalApiRequest {
|
|
6
|
+
url: string;
|
|
7
|
+
method?: string;
|
|
8
|
+
headers?: Record<string, string>;
|
|
9
|
+
/** Sent as JSON (with the JSON content type) unless `body` is given. */
|
|
10
|
+
json?: unknown;
|
|
11
|
+
/** Sent as is (a string, or URLSearchParams for a form). */
|
|
12
|
+
body?: string | URLSearchParams;
|
|
13
|
+
/** Overrides the gateway's timeout for this request. */
|
|
14
|
+
timeoutMs?: number;
|
|
15
|
+
/** Values to scrub out of what this request returns, besides the gateway's own (per-request credentials). */
|
|
16
|
+
secrets?: string[];
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* What a request answered — the `data` of the OpResult a request returns (on success AND on an HTTP refusal).
|
|
20
|
+
* ⚠ SCRUBBED: every secret of the gateway (and of the request) is replaced by `***` in the body and the headers, and
|
|
21
|
+
* `set-cookie` is dropped — the reply travels outward in the OpResult, and a service can echo a key back.
|
|
22
|
+
*/
|
|
23
|
+
export interface ExternalApiReply {
|
|
24
|
+
status: number;
|
|
25
|
+
headers: Record<string, string>;
|
|
26
|
+
/** The parsed JSON body, else the text, else null — at most 64 KB of it. */
|
|
27
|
+
body: any;
|
|
28
|
+
}
|
|
29
|
+
/** The most of a reply that is read: a hostile receiver must not be able to stream until memory runs out. */
|
|
30
|
+
export declare const MAX_REPLY_BYTES: number;
|
|
31
|
+
/** The longest wait a `Retry-After` may ask for and still be retried — longer, and the failure is returned at once. */
|
|
32
|
+
export declare const MAX_RETRY_WAIT_MS = 10000;
|
|
33
|
+
/** The standard OpResult code for an HTTP status that is not a success. Pure. */
|
|
34
|
+
export declare const opResultCodeOfHttpStatus: (status: number) => number;
|
|
35
|
+
declare abstract class BaseExternalApiGateway<TSettings extends Record<string, any> = Record<string, any>> {
|
|
36
|
+
protected logger: Logger;
|
|
37
|
+
protected baseUrl: string;
|
|
38
|
+
protected timeoutMs: number;
|
|
39
|
+
protected retries: number;
|
|
40
|
+
protected retryDelaysMs: number[];
|
|
41
|
+
protected fetchImpl: ExternalApiFetch;
|
|
42
|
+
private _settings;
|
|
43
|
+
private _credentials;
|
|
44
|
+
private _credentialsSet;
|
|
45
|
+
constructor(props?: BaseExternalApiGatewayPropsInterface<TSettings>);
|
|
46
|
+
/**
|
|
47
|
+
* Sets the gateway up. REPLACES whatever was set before (never merges), so re-pointing a shared instance at another
|
|
48
|
+
* tenant keeps nothing of the last one. Never throws: a setting that is missing or malformed is reported by
|
|
49
|
+
* `getConfigProblems()`, and every operation refuses with VALIDATION_FAILED until it is fixed.
|
|
50
|
+
*/
|
|
51
|
+
configure(settings: TSettings): this;
|
|
52
|
+
/** What is missing or malformed in the settings, in words — never a value. Empty when the gateway can be used. */
|
|
53
|
+
getConfigProblems(): string[];
|
|
54
|
+
/** True when the settings are complete and well-formed. */
|
|
55
|
+
isConfigured(): boolean;
|
|
56
|
+
/** The current settings. ⚠ They hold secrets: for the gateway itself, never to be logged or returned. */
|
|
57
|
+
protected get settings(): Readonly<Partial<TSettings>>;
|
|
58
|
+
/** What is wrong with these settings (override per gateway). */
|
|
59
|
+
protected validateSettings(_settings: Partial<TSettings>): string[];
|
|
60
|
+
/** The values to scrub out of every error message (override per gateway: keys, tokens, secret URLs). */
|
|
61
|
+
protected secretValues(): string[];
|
|
62
|
+
/** Called after every `configure` (override to rebuild an SDK client). */
|
|
63
|
+
protected onConfigured(): void;
|
|
64
|
+
/** The refusal every operation answers while the gateway is not set up. */
|
|
65
|
+
protected notConfigured(): OpResult;
|
|
66
|
+
/** `text` with every secret of this gateway (and `extra`) replaced by `***`. */
|
|
67
|
+
protected scrub(text: string, extra?: string[]): string;
|
|
68
|
+
/** `value` (a string, or anything JSON) with every secret replaced by `***`. */
|
|
69
|
+
protected scrubValue(value: any, extra?: string[]): any;
|
|
70
|
+
/** The words of a refusal, from the service's answer (override per gateway for its error shape). */
|
|
71
|
+
protected errorMessageOf(reply: ExternalApiReply): string;
|
|
72
|
+
/** Whether a failed attempt is worth repeating (override per gateway to refuse the hopeless ones). */
|
|
73
|
+
protected shouldRetry(result: OpResult): boolean;
|
|
74
|
+
/** How long the service asked us to wait before trying again, in ms (its `Retry-After`), or null. */
|
|
75
|
+
protected retryAfterMs(result: OpResult): number | null;
|
|
76
|
+
/**
|
|
77
|
+
* ONE attempt. OK with `{status, headers, body}` for a 2xx; else the standard code for the status (with the same data,
|
|
78
|
+
* so a gateway can read the service's own error), NETWORK_ERROR or TIMEOUT when nothing answered, VALIDATION_FAILED
|
|
79
|
+
* when the request itself could not be made (a malformed header). The reply is scrubbed and capped. Never throws.
|
|
80
|
+
* Redirects are not followed.
|
|
81
|
+
*/
|
|
82
|
+
protected request(req: ExternalApiRequest): Promise<OpResult>;
|
|
83
|
+
/**
|
|
84
|
+
* `request`, repeated while `shouldRetry` says a failure is worth it — after the service's `Retry-After` when it gave
|
|
85
|
+
* one (and not at all when it asks for longer than MAX_RETRY_WAIT_MS), else after the configured waits. Never throws.
|
|
86
|
+
*/
|
|
87
|
+
protected requestWithRetries(req: ExternalApiRequest): Promise<OpResult>;
|
|
88
|
+
setCredentials(credentials: string | Record<string, any>): this;
|
|
89
|
+
hasCredentials(): boolean;
|
|
90
|
+
protected get credentials(): string | Record<string, any>;
|
|
91
|
+
protected assertCredentials(): void;
|
|
92
|
+
protected onCredentialsSet(): void;
|
|
93
|
+
}
|
|
94
|
+
export { BaseExternalApiGateway };
|