@sdflc/backend-helpers 1.0.138 → 1.0.140
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 +176 -20
- package/build/BaseGateway.js +18 -2
- package/build/EmergencyAlerter.d.ts +140 -0
- package/build/EmergencyAlerter.js +465 -0
- package/build/esm/BaseGateway.js +18 -2
- 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,115 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.TelegramGw = exports.telegramVisibleLength = exports.isTelegramChatId = exports.TELEGRAM_MAX_MESSAGE_LENGTH = void 0;
|
|
4
|
+
// ./src/gateways/TelegramGw.ts
|
|
5
|
+
//
|
|
6
|
+
// Sends messages through the Telegram Bot API (https://core.telegram.org/bots/api#sendmessage). No SDK: one REST call.
|
|
7
|
+
//
|
|
8
|
+
// const telegram = new TelegramGw().configure({ botToken, chatId });
|
|
9
|
+
// const result = await telegram.sendMessage({ text: '<b>Hello</b>' });
|
|
10
|
+
//
|
|
11
|
+
// ⚠ The bot token sits in the request URL: it is scrubbed out of every error this returns.
|
|
12
|
+
// ⚠ A text over Telegram's 4096 characters is REFUSED, not cut: cutting finished HTML can split a tag or an entity, and
|
|
13
|
+
// Telegram then refuses the whole message anyway. A caller that sends long text cuts it BEFORE adding markup.
|
|
14
|
+
const api_helpers_1 = require("@sdflc/api-helpers");
|
|
15
|
+
const BaseExternalApiGateway_1 = require("./BaseExternalApiGateway");
|
|
16
|
+
/** The API's own limit on one message. */
|
|
17
|
+
exports.TELEGRAM_MAX_MESSAGE_LENGTH = 4096;
|
|
18
|
+
const TELEGRAM_BASE_URL = 'https://api.telegram.org';
|
|
19
|
+
const BOT_TOKEN_FORMAT = /^\d+:[A-Za-z0-9_-]+$/;
|
|
20
|
+
const CHAT_ID_FORMAT = /^(-?\d+|@[A-Za-z0-9_]{5,})$/;
|
|
21
|
+
/** True for a Telegram chat: a numeric id (negative for a group) or `@channelname`. Pure. */
|
|
22
|
+
const isTelegramChatId = (value) => CHAT_ID_FORMAT.test(String(value ?? '').trim());
|
|
23
|
+
exports.isTelegramChatId = isTelegramChatId;
|
|
24
|
+
/**
|
|
25
|
+
* The length Telegram counts — AFTER it parses the markup: tags are not characters, an entity is one. Pure.
|
|
26
|
+
* (For MarkdownV2 and plain text this is the raw length.)
|
|
27
|
+
*/
|
|
28
|
+
const telegramVisibleLength = (text, parseMode) => parseMode === 'HTML'
|
|
29
|
+
? String(text)
|
|
30
|
+
.replace(/<[^>]*>/g, '')
|
|
31
|
+
.replace(/&(?:#\d+|#x[0-9a-fA-F]+|[a-zA-Z]+);/g, '_').length
|
|
32
|
+
: String(text).length;
|
|
33
|
+
exports.telegramVisibleLength = telegramVisibleLength;
|
|
34
|
+
/** Refusals that will not change on a retry (a wrong chat, a blocked bot, a bad token, broken markup). */
|
|
35
|
+
const PERMANENT_DESCRIPTIONS = [
|
|
36
|
+
'bot was blocked',
|
|
37
|
+
'chat not found',
|
|
38
|
+
'bot is not a member',
|
|
39
|
+
'not enough rights',
|
|
40
|
+
'chat_write_forbidden',
|
|
41
|
+
'bot was kicked',
|
|
42
|
+
'user is deactivated',
|
|
43
|
+
'invalid token',
|
|
44
|
+
"can't parse entities",
|
|
45
|
+
];
|
|
46
|
+
class TelegramGw extends BaseExternalApiGateway_1.BaseExternalApiGateway {
|
|
47
|
+
constructor(props) {
|
|
48
|
+
super({ baseUrl: TELEGRAM_BASE_URL, ...(props ?? {}) });
|
|
49
|
+
}
|
|
50
|
+
validateSettings(settings) {
|
|
51
|
+
const problems = [];
|
|
52
|
+
if (!BOT_TOKEN_FORMAT.test(String(settings.botToken ?? '').trim())) {
|
|
53
|
+
problems.push('the bot token is missing or malformed (expected <id>:<secret> from @BotFather)');
|
|
54
|
+
}
|
|
55
|
+
if (settings.chatId !== undefined && settings.chatId !== '' && !(0, exports.isTelegramChatId)(settings.chatId)) {
|
|
56
|
+
problems.push('the chat id is malformed (a numeric id, or @channelname)');
|
|
57
|
+
}
|
|
58
|
+
return problems;
|
|
59
|
+
}
|
|
60
|
+
secretValues() {
|
|
61
|
+
return [String(this.settings.botToken ?? '').trim()];
|
|
62
|
+
}
|
|
63
|
+
errorMessageOf(reply) {
|
|
64
|
+
return String(reply.body?.description ?? super.errorMessageOf(reply)).slice(0, 500);
|
|
65
|
+
}
|
|
66
|
+
shouldRetry(result) {
|
|
67
|
+
const description = String(result.getDataFirst()?.body?.description ?? result.getErrorSummary('')).toLowerCase();
|
|
68
|
+
return !PERMANENT_DESCRIPTIONS.some((one) => description.includes(one)) && super.shouldRetry(result);
|
|
69
|
+
}
|
|
70
|
+
/** Telegram says how long to wait in its body (`parameters.retry_after`, seconds), not only in a header. */
|
|
71
|
+
retryAfterMs(result) {
|
|
72
|
+
const seconds = Number(result.getDataFirst()?.body?.parameters?.retry_after);
|
|
73
|
+
return Number.isFinite(seconds) && seconds >= 0 ? seconds * 1000 : super.retryAfterMs(result);
|
|
74
|
+
}
|
|
75
|
+
/** Sends one message. OK with `{ messageId }`. Never throws. */
|
|
76
|
+
async sendMessage(message) {
|
|
77
|
+
if (!this.isConfigured()) {
|
|
78
|
+
return this.notConfigured();
|
|
79
|
+
}
|
|
80
|
+
const chatId = String(message?.chatId ?? this.settings.chatId ?? '').trim();
|
|
81
|
+
const text = String(message?.text ?? '');
|
|
82
|
+
if (!(0, exports.isTelegramChatId)(chatId)) {
|
|
83
|
+
return api_helpers_1.OpResult.fail(api_helpers_1.OP_RESULT_CODES.VALIDATION_FAILED, null, 'There is no chat to send to (configure chatId or pass it)');
|
|
84
|
+
}
|
|
85
|
+
if (!text) {
|
|
86
|
+
return api_helpers_1.OpResult.fail(api_helpers_1.OP_RESULT_CODES.VALIDATION_FAILED, null, 'The message is empty');
|
|
87
|
+
}
|
|
88
|
+
const parseMode = message.parseMode === null ? undefined : (message.parseMode ?? this.settings.parseMode ?? 'HTML');
|
|
89
|
+
const length = (0, exports.telegramVisibleLength)(text, parseMode);
|
|
90
|
+
if (length > exports.TELEGRAM_MAX_MESSAGE_LENGTH) {
|
|
91
|
+
return api_helpers_1.OpResult.fail(api_helpers_1.OP_RESULT_CODES.VALIDATION_FAILED, null, `The message is ${length} characters; Telegram allows ${exports.TELEGRAM_MAX_MESSAGE_LENGTH}`);
|
|
92
|
+
}
|
|
93
|
+
const result = await this.requestWithRetries({
|
|
94
|
+
url: `${this.baseUrl}/bot${String(this.settings.botToken).trim()}/sendMessage`,
|
|
95
|
+
json: {
|
|
96
|
+
chat_id: chatId,
|
|
97
|
+
text,
|
|
98
|
+
...(parseMode ? { parse_mode: parseMode } : {}),
|
|
99
|
+
disable_web_page_preview: message.disableWebPagePreview !== false,
|
|
100
|
+
...(message.disableNotification ? { disable_notification: true } : {}),
|
|
101
|
+
...(message.inlineKeyboard ? { reply_markup: { inline_keyboard: message.inlineKeyboard } } : {}),
|
|
102
|
+
},
|
|
103
|
+
});
|
|
104
|
+
if (result.didFail()) {
|
|
105
|
+
return result;
|
|
106
|
+
}
|
|
107
|
+
const body = result.getDataFirst()?.body;
|
|
108
|
+
// A 200 with `ok: false` is a refusal too.
|
|
109
|
+
if (body?.ok !== true) {
|
|
110
|
+
return api_helpers_1.OpResult.fail(api_helpers_1.OP_RESULT_CODES.FAILED, null, this.scrub(String(body?.description ?? 'Telegram did not accept the message')));
|
|
111
|
+
}
|
|
112
|
+
return api_helpers_1.OpResult.ok([{ messageId: body?.result?.message_id ?? null }]);
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
exports.TelegramGw = TelegramGw;
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import { OpResult } from '@sdflc/api-helpers';
|
|
2
|
+
import { BaseExternalApiGatewayPropsInterface } from '../interfaces';
|
|
3
|
+
import { BaseExternalApiGateway, ExternalApiReply } from './BaseExternalApiGateway';
|
|
4
|
+
export interface TwilioSettings {
|
|
5
|
+
/** `AC` + 32 hex characters */
|
|
6
|
+
accountSid: string;
|
|
7
|
+
authToken: string;
|
|
8
|
+
/** The default sender (a number, or `whatsapp:+…`); or send through a messaging service instead. */
|
|
9
|
+
from?: string;
|
|
10
|
+
messagingServiceSid?: string;
|
|
11
|
+
}
|
|
12
|
+
export interface TwilioMessage {
|
|
13
|
+
/** E.164 (`+15557654321`), or `whatsapp:+15557654321` */
|
|
14
|
+
to: string;
|
|
15
|
+
body: string;
|
|
16
|
+
from?: string;
|
|
17
|
+
/** Where Twilio reports delivery status. */
|
|
18
|
+
statusCallback?: string;
|
|
19
|
+
mediaUrl?: string[];
|
|
20
|
+
}
|
|
21
|
+
/** Twilio's limit on one message body. */
|
|
22
|
+
export declare const TWILIO_MAX_BODY_LENGTH = 1600;
|
|
23
|
+
declare class TwilioGw extends BaseExternalApiGateway<TwilioSettings> {
|
|
24
|
+
constructor(props?: BaseExternalApiGatewayPropsInterface<TwilioSettings>);
|
|
25
|
+
protected validateSettings(settings: Partial<TwilioSettings>): string[];
|
|
26
|
+
protected secretValues(): string[];
|
|
27
|
+
/** ⚠ Not after a TIMEOUT: Twilio may well have accepted the message, and a retry texts the person twice. */
|
|
28
|
+
protected shouldRetry(result: OpResult): boolean;
|
|
29
|
+
protected errorMessageOf(reply: ExternalApiReply): string;
|
|
30
|
+
/** Sends one message. OK with `{ sid, status }`. Never throws. */
|
|
31
|
+
sendMessage(message: TwilioMessage): Promise<OpResult>;
|
|
32
|
+
}
|
|
33
|
+
export { TwilioGw };
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.TwilioGw = exports.TWILIO_MAX_BODY_LENGTH = void 0;
|
|
4
|
+
// ./src/gateways/TwilioGw.ts
|
|
5
|
+
//
|
|
6
|
+
// Sends SMS (and WhatsApp, with `whatsapp:` addresses) through Twilio's Messages API
|
|
7
|
+
// (POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages.json). No SDK: one REST call.
|
|
8
|
+
//
|
|
9
|
+
// const twilio = new TwilioGw().configure({ accountSid, authToken, from: '+15551234567' });
|
|
10
|
+
// const result = await twilio.sendMessage({ to: '+15557654321', body: 'Hello' });
|
|
11
|
+
//
|
|
12
|
+
// ⚠ The auth token is scrubbed out of every error this returns.
|
|
13
|
+
const buffer_1 = require("buffer");
|
|
14
|
+
const api_helpers_1 = require("@sdflc/api-helpers");
|
|
15
|
+
const BaseExternalApiGateway_1 = require("./BaseExternalApiGateway");
|
|
16
|
+
const TWILIO_BASE_URL = 'https://api.twilio.com';
|
|
17
|
+
const ACCOUNT_SID_FORMAT = /^AC[0-9a-fA-F]{32}$/;
|
|
18
|
+
const ADDRESS_FORMAT = /^(whatsapp:)?\+[1-9]\d{6,14}$/;
|
|
19
|
+
/** Twilio's limit on one message body. */
|
|
20
|
+
exports.TWILIO_MAX_BODY_LENGTH = 1600;
|
|
21
|
+
class TwilioGw extends BaseExternalApiGateway_1.BaseExternalApiGateway {
|
|
22
|
+
constructor(props) {
|
|
23
|
+
super({ baseUrl: TWILIO_BASE_URL, ...(props ?? {}) });
|
|
24
|
+
}
|
|
25
|
+
validateSettings(settings) {
|
|
26
|
+
const problems = [];
|
|
27
|
+
if (!ACCOUNT_SID_FORMAT.test(String(settings.accountSid ?? '').trim())) {
|
|
28
|
+
problems.push('the account SID is missing or malformed (AC + 32 hex characters)');
|
|
29
|
+
}
|
|
30
|
+
if (!String(settings.authToken ?? '').trim()) {
|
|
31
|
+
problems.push('the auth token is missing');
|
|
32
|
+
}
|
|
33
|
+
if (settings.from && !ADDRESS_FORMAT.test(String(settings.from).trim())) {
|
|
34
|
+
problems.push('the From number is not E.164 (+15551234567, or whatsapp:+15551234567)');
|
|
35
|
+
}
|
|
36
|
+
return problems;
|
|
37
|
+
}
|
|
38
|
+
secretValues() {
|
|
39
|
+
const sid = String(this.settings.accountSid ?? '').trim();
|
|
40
|
+
const token = String(this.settings.authToken ?? '').trim();
|
|
41
|
+
return [token, buffer_1.Buffer.from(`${sid}:${token}`).toString('base64')];
|
|
42
|
+
}
|
|
43
|
+
/** ⚠ Not after a TIMEOUT: Twilio may well have accepted the message, and a retry texts the person twice. */
|
|
44
|
+
shouldRetry(result) {
|
|
45
|
+
return result.getCode() !== api_helpers_1.OP_RESULT_CODES.TIMEOUT && super.shouldRetry(result);
|
|
46
|
+
}
|
|
47
|
+
errorMessageOf(reply) {
|
|
48
|
+
const body = reply.body;
|
|
49
|
+
if (body && typeof body === 'object' && body.message) {
|
|
50
|
+
return `${body.message}${body.code ? ` (Twilio ${body.code})` : ''}`.slice(0, 500);
|
|
51
|
+
}
|
|
52
|
+
return super.errorMessageOf(reply);
|
|
53
|
+
}
|
|
54
|
+
/** Sends one message. OK with `{ sid, status }`. Never throws. */
|
|
55
|
+
async sendMessage(message) {
|
|
56
|
+
if (!this.isConfigured()) {
|
|
57
|
+
return this.notConfigured();
|
|
58
|
+
}
|
|
59
|
+
const to = String(message?.to ?? '').trim();
|
|
60
|
+
const from = String(message?.from ?? this.settings.from ?? '').trim();
|
|
61
|
+
const body = String(message?.body ?? '');
|
|
62
|
+
const problems = [];
|
|
63
|
+
if (!ADDRESS_FORMAT.test(to)) {
|
|
64
|
+
problems.push('the recipient is not E.164 (+15557654321, or whatsapp:+15557654321)');
|
|
65
|
+
}
|
|
66
|
+
if (!from && !this.settings.messagingServiceSid) {
|
|
67
|
+
problems.push('there is no sender (configure from or messagingServiceSid, or pass from)');
|
|
68
|
+
}
|
|
69
|
+
if (from && !ADDRESS_FORMAT.test(from)) {
|
|
70
|
+
problems.push('the sender is not E.164');
|
|
71
|
+
}
|
|
72
|
+
if (!body) {
|
|
73
|
+
problems.push('the message is empty');
|
|
74
|
+
}
|
|
75
|
+
else if (body.length > exports.TWILIO_MAX_BODY_LENGTH) {
|
|
76
|
+
problems.push(`the message is ${body.length} characters; Twilio allows ${exports.TWILIO_MAX_BODY_LENGTH}`);
|
|
77
|
+
}
|
|
78
|
+
if (problems.length) {
|
|
79
|
+
return api_helpers_1.OpResult.fail(api_helpers_1.OP_RESULT_CODES.VALIDATION_FAILED, null, `The message cannot be sent: ${problems.join('; ')}`);
|
|
80
|
+
}
|
|
81
|
+
const form = new URLSearchParams();
|
|
82
|
+
form.set('To', to);
|
|
83
|
+
form.set('Body', body);
|
|
84
|
+
if (from) {
|
|
85
|
+
form.set('From', from);
|
|
86
|
+
}
|
|
87
|
+
else {
|
|
88
|
+
form.set('MessagingServiceSid', String(this.settings.messagingServiceSid));
|
|
89
|
+
}
|
|
90
|
+
if (message.statusCallback) {
|
|
91
|
+
form.set('StatusCallback', message.statusCallback);
|
|
92
|
+
}
|
|
93
|
+
for (const url of message.mediaUrl ?? []) {
|
|
94
|
+
form.append('MediaUrl', url);
|
|
95
|
+
}
|
|
96
|
+
const sid = String(this.settings.accountSid).trim();
|
|
97
|
+
const auth = buffer_1.Buffer.from(`${sid}:${String(this.settings.authToken).trim()}`).toString('base64');
|
|
98
|
+
const result = await this.requestWithRetries({
|
|
99
|
+
url: `${this.baseUrl}/2010-04-01/Accounts/${sid}/Messages.json`,
|
|
100
|
+
headers: { Authorization: `Basic ${auth}`, 'Content-Type': 'application/x-www-form-urlencoded' },
|
|
101
|
+
body: form,
|
|
102
|
+
});
|
|
103
|
+
if (result.didFail()) {
|
|
104
|
+
return result;
|
|
105
|
+
}
|
|
106
|
+
const reply = result.getDataFirst()?.body;
|
|
107
|
+
return api_helpers_1.OpResult.ok([{ sid: reply?.sid ?? null, status: reply?.status ?? null }]);
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
exports.TwilioGw = 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,121 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.checkExternalUrl = exports.isBlockedAddress = void 0;
|
|
4
|
+
// ./src/gateways/externalUrl.ts
|
|
5
|
+
//
|
|
6
|
+
// 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
|
|
7
|
+
// network: localhost, the private ranges, the cloud metadata service (169.254.169.254 hands out credentials), or any of
|
|
8
|
+
// them spelled another way (an IPv4 address written as IPv6, a hostname that resolves to one).
|
|
9
|
+
//
|
|
10
|
+
// ⚠ EVERY address a hostname resolves to is checked — a name with one public and one private address is refused.
|
|
11
|
+
// ⚠ What it cannot stop alone: a hostname that resolves to a public address now and a private one at the moment of the
|
|
12
|
+
// request (DNS rebinding). Gateways that use this also refuse to follow redirects; together that narrows it to a
|
|
13
|
+
// window of milliseconds, not closes it.
|
|
14
|
+
const net_1 = require("net");
|
|
15
|
+
const dns_1 = require("dns");
|
|
16
|
+
const api_helpers_1 = require("@sdflc/api-helpers");
|
|
17
|
+
const BLOCKED = new net_1.BlockList();
|
|
18
|
+
// IPv4: "this network", private, carrier-grade NAT, loopback, link-local (metadata), protocol assignments, test nets,
|
|
19
|
+
// benchmarking, multicast, reserved, broadcast.
|
|
20
|
+
for (const [network, prefix] of [
|
|
21
|
+
['0.0.0.0', 8],
|
|
22
|
+
['10.0.0.0', 8],
|
|
23
|
+
['100.64.0.0', 10],
|
|
24
|
+
['127.0.0.0', 8],
|
|
25
|
+
['169.254.0.0', 16],
|
|
26
|
+
['172.16.0.0', 12],
|
|
27
|
+
['192.0.0.0', 24],
|
|
28
|
+
['192.0.2.0', 24],
|
|
29
|
+
['192.168.0.0', 16],
|
|
30
|
+
['198.18.0.0', 15],
|
|
31
|
+
['192.88.99.0', 24],
|
|
32
|
+
['198.51.100.0', 24],
|
|
33
|
+
['203.0.113.0', 24],
|
|
34
|
+
['224.0.0.0', 4],
|
|
35
|
+
['240.0.0.0', 4],
|
|
36
|
+
]) {
|
|
37
|
+
BLOCKED.addSubnet(network, prefix, 'ipv4');
|
|
38
|
+
}
|
|
39
|
+
// IPv6: unspecified, loopback, IPv4-compatible (`::127.0.0.1`), NAT64 — both prefixes — and 6to4 (all reach IPv4
|
|
40
|
+
// inside), discard-only, documentation, unique-local (fc00::/7 = fc… AND fd…), link-local, multicast.
|
|
41
|
+
// ⓘ IPv4-MAPPED (`::ffff:127.0.0.1`) needs no rule of its own: BlockList checks it against the IPv4 rules.
|
|
42
|
+
for (const [network, prefix] of [
|
|
43
|
+
['::', 128],
|
|
44
|
+
['::1', 128],
|
|
45
|
+
['::', 96],
|
|
46
|
+
['64:ff9b::', 96],
|
|
47
|
+
['64:ff9b:1::', 48],
|
|
48
|
+
['100::', 64],
|
|
49
|
+
['2002::', 16],
|
|
50
|
+
['2001:db8::', 32],
|
|
51
|
+
['fc00::', 7],
|
|
52
|
+
['fe80::', 10],
|
|
53
|
+
['ff00::', 8],
|
|
54
|
+
]) {
|
|
55
|
+
BLOCKED.addSubnet(network, prefix, 'ipv6');
|
|
56
|
+
}
|
|
57
|
+
const BLOCKED_HOSTNAMES = new Set(['localhost', 'localhost.localdomain', 'metadata', 'metadata.google.internal']);
|
|
58
|
+
/** True when an IP address is one a user-given URL must never reach. Pure. */
|
|
59
|
+
const isBlockedAddress = (address) => {
|
|
60
|
+
const ip = String(address ?? '')
|
|
61
|
+
.replace(/^\[|\]$/g, '')
|
|
62
|
+
.split('%')[0];
|
|
63
|
+
const version = (0, net_1.isIP)(ip);
|
|
64
|
+
if (version === 4) {
|
|
65
|
+
return BLOCKED.check(ip, 'ipv4');
|
|
66
|
+
}
|
|
67
|
+
if (version === 6) {
|
|
68
|
+
// ⓘ BlockList matches an IPv4-MAPPED address (`::ffff:127.0.0.1`, `::ffff:7f00:1`) against the IPv4 rules itself.
|
|
69
|
+
return BLOCKED.check(ip, 'ipv6');
|
|
70
|
+
}
|
|
71
|
+
// Not an address at all: refuse rather than guess.
|
|
72
|
+
return true;
|
|
73
|
+
};
|
|
74
|
+
exports.isBlockedAddress = isBlockedAddress;
|
|
75
|
+
const systemLookup = async (hostname) => (await dns_1.promises.lookup(hostname, { all: true, verbatim: true })).map((one) => one.address);
|
|
76
|
+
/**
|
|
77
|
+
* OK when `url` may be requested: a permitted protocol, no credentials in it, and a host that is not — and does not
|
|
78
|
+
* resolve to — a local, private or reserved address. Else VALIDATION_FAILED, saying why. Never throws.
|
|
79
|
+
*/
|
|
80
|
+
const checkExternalUrl = async (url, opts = {}) => {
|
|
81
|
+
const field = opts.field ?? '';
|
|
82
|
+
const refuse = (why) => api_helpers_1.OpResult.fail(api_helpers_1.OP_RESULT_CODES.VALIDATION_FAILED, null, { [field]: why });
|
|
83
|
+
let parsed;
|
|
84
|
+
try {
|
|
85
|
+
parsed = new URL(String(url ?? '').trim());
|
|
86
|
+
}
|
|
87
|
+
catch {
|
|
88
|
+
return refuse('The URL is not valid');
|
|
89
|
+
}
|
|
90
|
+
if (!(opts.protocols ?? ['https:', 'http:']).includes(parsed.protocol)) {
|
|
91
|
+
return refuse(`Only ${(opts.protocols ?? ['https:', 'http:']).join(' and ')} URLs are allowed`);
|
|
92
|
+
}
|
|
93
|
+
if (parsed.username || parsed.password) {
|
|
94
|
+
return refuse('A URL must not carry a user name or password');
|
|
95
|
+
}
|
|
96
|
+
const host = parsed.hostname
|
|
97
|
+
.toLowerCase()
|
|
98
|
+
.replace(/^\[|\]$/g, '')
|
|
99
|
+
.replace(/\.$/, '');
|
|
100
|
+
if (!host || BLOCKED_HOSTNAMES.has(host) || host.endsWith('.localhost') || host.endsWith('.internal')) {
|
|
101
|
+
return refuse('This host is not allowed');
|
|
102
|
+
}
|
|
103
|
+
if ((0, net_1.isIP)(host)) {
|
|
104
|
+
return (0, exports.isBlockedAddress)(host) ? refuse('This address is not allowed') : api_helpers_1.OpResult.ok([]);
|
|
105
|
+
}
|
|
106
|
+
let addresses;
|
|
107
|
+
try {
|
|
108
|
+
addresses = await (opts.lookup ?? systemLookup)(host);
|
|
109
|
+
}
|
|
110
|
+
catch {
|
|
111
|
+
return refuse('The host name does not resolve');
|
|
112
|
+
}
|
|
113
|
+
if (!addresses.length) {
|
|
114
|
+
return refuse('The host name does not resolve');
|
|
115
|
+
}
|
|
116
|
+
// ⚠ EVERY address: a name with one public and one private address is refused.
|
|
117
|
+
return addresses.some(exports.isBlockedAddress)
|
|
118
|
+
? refuse('The host name resolves to an address that is not allowed')
|
|
119
|
+
: api_helpers_1.OpResult.ok([]);
|
|
120
|
+
};
|
|
121
|
+
exports.checkExternalUrl = checkExternalUrl;
|
|
@@ -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,141 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
3
|
+
return (mod && mod.__esModule) ? mod : { "default": mod };
|
|
4
|
+
};
|
|
5
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
6
|
+
exports.createGuardedFetch = exports.guardedLookup = void 0;
|
|
7
|
+
// ./src/gateways/guardedFetch.ts
|
|
8
|
+
//
|
|
9
|
+
// A `fetch` for URLs a USER gave us (webhooks) that refuses a forbidden address AT THE MOMENT OF CONNECTING.
|
|
10
|
+
//
|
|
11
|
+
// ⚠ WHY NOT JUST CHECK THE URL FIRST: `checkExternalUrl` resolves the host name once; the platform fetch then resolves it
|
|
12
|
+
// AGAIN, on every attempt. A DNS server that answers a public address to the first lookup and 169.254.169.254 to the
|
|
13
|
+
// second (DNS rebinding) walks straight past a check made beforehand. Here the address the socket actually connects
|
|
14
|
+
// to is the one checked: Node's `http(s).request` takes the lookup, and this lookup refuses a blocked address.
|
|
15
|
+
// ⚠ An IP written in the URL is never looked up — it is checked here directly.
|
|
16
|
+
// ⚠ Redirects are never followed (http.request does not), the reply is capped at MAX_REPLY_BYTES, and the request ends at
|
|
17
|
+
// its signal (the gateway's timeout).
|
|
18
|
+
const http_1 = __importDefault(require("http"));
|
|
19
|
+
const https_1 = __importDefault(require("https"));
|
|
20
|
+
const buffer_1 = require("buffer");
|
|
21
|
+
const net_1 = require("net");
|
|
22
|
+
const dns_1 = require("dns");
|
|
23
|
+
const BaseExternalApiGateway_1 = require("./BaseExternalApiGateway");
|
|
24
|
+
const externalUrl_1 = require("./externalUrl");
|
|
25
|
+
/** The error a refused address raises — the gateway reports it as VALIDATION_FAILED, never retried. */
|
|
26
|
+
const blockedError = (address) => Object.assign(new Error(`The address ${address} is not allowed`), { code: 'EBLOCKED' });
|
|
27
|
+
/**
|
|
28
|
+
* A `dns.lookup` that refuses when ANY address the name resolves to is blocked (a name with one private address among
|
|
29
|
+
* public ones is refused, whichever the socket would have picked).
|
|
30
|
+
*/
|
|
31
|
+
const guardedLookup = (opts = {}) => (hostname, options, callback) => {
|
|
32
|
+
const resolve = opts.dnsLookup ?? dns_1.lookup;
|
|
33
|
+
const isBlocked = opts.isBlocked ?? externalUrl_1.isBlockedAddress;
|
|
34
|
+
const wantsAll = typeof options === 'object' && options?.all === true;
|
|
35
|
+
resolve(hostname, { ...(typeof options === 'object' ? options : {}), all: true }, (err, addresses) => {
|
|
36
|
+
if (err) {
|
|
37
|
+
callback(err);
|
|
38
|
+
return;
|
|
39
|
+
}
|
|
40
|
+
const list = Array.isArray(addresses) ? addresses : [];
|
|
41
|
+
const refused = list.find((one) => isBlocked(String(one?.address)));
|
|
42
|
+
if (refused || list.length === 0) {
|
|
43
|
+
callback(refused
|
|
44
|
+
? blockedError(String(refused.address))
|
|
45
|
+
: Object.assign(new Error(`${hostname} did not resolve`), { code: 'ENOTFOUND' }));
|
|
46
|
+
return;
|
|
47
|
+
}
|
|
48
|
+
if (wantsAll) {
|
|
49
|
+
callback(null, list);
|
|
50
|
+
}
|
|
51
|
+
else {
|
|
52
|
+
callback(null, list[0].address, list[0].family);
|
|
53
|
+
}
|
|
54
|
+
});
|
|
55
|
+
};
|
|
56
|
+
exports.guardedLookup = guardedLookup;
|
|
57
|
+
/** A fetch whose every connection goes through `guardedLookup`. The answer has `status`, `headers` and `text()`. */
|
|
58
|
+
const createGuardedFetch = (opts = {}) => {
|
|
59
|
+
const isBlocked = opts.isBlocked ?? externalUrl_1.isBlockedAddress;
|
|
60
|
+
return (url, init = {}) => new Promise((resolve, reject) => {
|
|
61
|
+
let target;
|
|
62
|
+
try {
|
|
63
|
+
target = new URL(url);
|
|
64
|
+
}
|
|
65
|
+
catch {
|
|
66
|
+
reject(new TypeError('Invalid URL'));
|
|
67
|
+
return;
|
|
68
|
+
}
|
|
69
|
+
const literal = target.hostname.replace(/^\[|\]$/g, '');
|
|
70
|
+
if ((0, net_1.isIP)(literal) && isBlocked(literal)) {
|
|
71
|
+
reject(blockedError(literal));
|
|
72
|
+
return;
|
|
73
|
+
}
|
|
74
|
+
const signal = init.signal;
|
|
75
|
+
if (signal?.aborted) {
|
|
76
|
+
reject(signal.reason);
|
|
77
|
+
return;
|
|
78
|
+
}
|
|
79
|
+
const transport = target.protocol === 'https:' ? https_1.default : target.protocol === 'http:' ? http_1.default : null;
|
|
80
|
+
if (!transport) {
|
|
81
|
+
reject(new TypeError(`Unsupported protocol ${target.protocol}`));
|
|
82
|
+
return;
|
|
83
|
+
}
|
|
84
|
+
let req;
|
|
85
|
+
try {
|
|
86
|
+
req = transport.request(target, {
|
|
87
|
+
method: init.method ?? 'GET',
|
|
88
|
+
headers: init.headers ?? {},
|
|
89
|
+
lookup: (0, exports.guardedLookup)(opts),
|
|
90
|
+
});
|
|
91
|
+
}
|
|
92
|
+
catch (e) {
|
|
93
|
+
// A malformed header is refused synchronously.
|
|
94
|
+
reject(e instanceof TypeError ? e : new TypeError(String(e?.message ?? e)));
|
|
95
|
+
return;
|
|
96
|
+
}
|
|
97
|
+
const onAbort = () => req.destroy(signal?.reason);
|
|
98
|
+
signal?.addEventListener('abort', onAbort, { once: true });
|
|
99
|
+
req.on('error', (e) => {
|
|
100
|
+
signal?.removeEventListener('abort', onAbort);
|
|
101
|
+
reject(e);
|
|
102
|
+
});
|
|
103
|
+
req.on('response', (res) => {
|
|
104
|
+
const chunks = [];
|
|
105
|
+
let size = 0;
|
|
106
|
+
let settled = false;
|
|
107
|
+
const finish = () => {
|
|
108
|
+
if (settled) {
|
|
109
|
+
return;
|
|
110
|
+
}
|
|
111
|
+
settled = true;
|
|
112
|
+
signal?.removeEventListener('abort', onAbort);
|
|
113
|
+
const text = buffer_1.Buffer.concat(chunks).toString('utf8');
|
|
114
|
+
resolve({ status: res.statusCode ?? 0, headers: { ...res.headers }, text: async () => text });
|
|
115
|
+
};
|
|
116
|
+
res.on('data', (chunk) => {
|
|
117
|
+
if (size + chunk.length > BaseExternalApiGateway_1.MAX_REPLY_BYTES) {
|
|
118
|
+
chunks.push(chunk.subarray(0, BaseExternalApiGateway_1.MAX_REPLY_BYTES - size));
|
|
119
|
+
size = BaseExternalApiGateway_1.MAX_REPLY_BYTES;
|
|
120
|
+
finish();
|
|
121
|
+
res.destroy();
|
|
122
|
+
return;
|
|
123
|
+
}
|
|
124
|
+
chunks.push(chunk);
|
|
125
|
+
size += chunk.length;
|
|
126
|
+
});
|
|
127
|
+
res.on('end', finish);
|
|
128
|
+
res.on('error', (e) => {
|
|
129
|
+
if (!settled) {
|
|
130
|
+
settled = true;
|
|
131
|
+
reject(e);
|
|
132
|
+
}
|
|
133
|
+
});
|
|
134
|
+
});
|
|
135
|
+
if (init.body !== undefined && init.body !== null) {
|
|
136
|
+
req.write(typeof init.body === 'string' ? init.body : String(init.body));
|
|
137
|
+
}
|
|
138
|
+
req.end();
|
|
139
|
+
});
|
|
140
|
+
};
|
|
141
|
+
exports.createGuardedFetch = createGuardedFetch;
|
|
@@ -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,25 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
|
|
3
|
+
if (k2 === undefined) k2 = k;
|
|
4
|
+
var desc = Object.getOwnPropertyDescriptor(m, k);
|
|
5
|
+
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
|
|
6
|
+
desc = { enumerable: true, get: function() { return m[k]; } };
|
|
7
|
+
}
|
|
8
|
+
Object.defineProperty(o, k2, desc);
|
|
9
|
+
}) : (function(o, m, k, k2) {
|
|
10
|
+
if (k2 === undefined) k2 = k;
|
|
11
|
+
o[k2] = m[k];
|
|
12
|
+
}));
|
|
13
|
+
var __exportStar = (this && this.__exportStar) || function(m, exports) {
|
|
14
|
+
for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
|
|
15
|
+
};
|
|
16
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
17
|
+
__exportStar(require("./BaseExternalApiGateway"), exports);
|
|
18
|
+
__exportStar(require("./externalUrl"), exports);
|
|
19
|
+
__exportStar(require("./SendGridGw"), exports);
|
|
20
|
+
__exportStar(require("./TelegramGw"), exports);
|
|
21
|
+
__exportStar(require("./TwilioGw"), exports);
|
|
22
|
+
__exportStar(require("./SlackWebhookGw"), exports);
|
|
23
|
+
__exportStar(require("./DiscordWebhookGw"), exports);
|
|
24
|
+
__exportStar(require("./HttpWebhookGw"), exports);
|
|
25
|
+
__exportStar(require("./guardedFetch"), exports);
|
package/build/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/index.js
CHANGED
|
@@ -37,6 +37,7 @@ __exportStar(require("./commonValidators"), exports);
|
|
|
37
37
|
__exportStar(require("./downloadHelpers"), exports);
|
|
38
38
|
__exportStar(require("./resolveClientIp"), exports);
|
|
39
39
|
__exportStar(require("./BaseRestApiCrudController"), exports);
|
|
40
|
-
__exportStar(require("./
|
|
40
|
+
__exportStar(require("./gateways"), exports);
|
|
41
41
|
__exportStar(require("./IpRateLimiter"), exports);
|
|
42
42
|
__exportStar(require("./uuidHelpers"), exports);
|
|
43
|
+
__exportStar(require("./EmergencyAlerter"), exports);
|
|
@@ -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
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@sdflc/backend-helpers",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.140",
|
|
4
4
|
"description": "Set of helper functions and classes to simplify building backend apps within @sdflc ecosystem",
|
|
5
5
|
"type": "commonjs",
|
|
6
6
|
"exports": {
|
|
@@ -20,6 +20,7 @@
|
|
|
20
20
|
"lint": "ESLINT_USE_FLAT_CONFIG=true eslint .",
|
|
21
21
|
"test": "echo No Tests Available Yet",
|
|
22
22
|
"testToDo": "jest --config jest.config.ts",
|
|
23
|
+
"prove": "node scripts/proveCreateId.cjs && node scripts/proveGateways.cjs && node scripts/proveEmergencyAlerter.cjs",
|
|
23
24
|
"format": "prettier --write \"src/**/*.ts\"",
|
|
24
25
|
"prepare": "husky",
|
|
25
26
|
"prepare1": "husky install",
|