@theokit/gateway-sms 0.2.3 → 0.3.1
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/CHANGELOG.md +110 -0
- package/README.md +13 -0
- package/dist/index.cjs +65 -68
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +92 -1
- package/dist/index.d.ts +92 -1
- package/dist/index.js +66 -70
- package/dist/index.js.map +1 -1
- package/package.json +3 -3
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,115 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.3.1
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- 1e215ab: The peer floor on `@theokit/gateway` is `>=0.9.0`, which is what these packages have needed since
|
|
8
|
+
they gained `deliver`.
|
|
9
|
+
|
|
10
|
+
`deliver` and `runHandler` arrived in the core at 0.9.0, and the previous release shipped these
|
|
11
|
+
adapters still declaring `>=0.6.0` — a floor `dep-check` had already proven false by building the
|
|
12
|
+
workspace against it: TS4113 on the override, TS2551 on `runHandler`, in all ten packages.
|
|
13
|
+
|
|
14
|
+
It could not be corrected in that release. `dep-check`'s install check packs an adapter and installs
|
|
15
|
+
it the way a consumer would, and until 0.9.0 was on npm no consumer could resolve a package asking
|
|
16
|
+
for it — the check was right about the world as it stood. The floor is raised here, against a
|
|
17
|
+
registry where the version it names exists.
|
|
18
|
+
|
|
19
|
+
Between the two releases a consumer installing against an older core got a build error rather than a
|
|
20
|
+
resolution error: the same failure, later and less clearly. That window is closed.
|
|
21
|
+
|
|
22
|
+
## 0.3.0
|
|
23
|
+
|
|
24
|
+
### Minor Changes
|
|
25
|
+
|
|
26
|
+
- b38172b: **The peer floor on `@theokit/gateway` rises with this release.** Every adapter now implements
|
|
27
|
+
`deliver` over `runHandler`, and neither exists in an older core — an adapter installed against one
|
|
28
|
+
does not build. `dep-check` caught that by building the whole workspace against the floor each
|
|
29
|
+
package claimed, which is the one thing a version range cannot tell you by reading it.
|
|
30
|
+
|
|
31
|
+
The floor is set in the version commit rather than here, because a range cannot name a version that
|
|
32
|
+
does not exist yet: raised in the workspace, the same gate then fails the other way round — every
|
|
33
|
+
adapter declaring a floor above the core installed beside it. That is the shape `fa70153` used when
|
|
34
|
+
these ranges were first written.
|
|
35
|
+
|
|
36
|
+
`deliver(event)` — every adapter can now be handed an event that arrived out of band (#83).
|
|
37
|
+
|
|
38
|
+
`onInbound` was the seam every adapter implemented and it had no public counterpart. Six platforms
|
|
39
|
+
self-deliver once connected — long polling, a gateway socket, Socket Mode, a sync loop, IMAP — so
|
|
40
|
+
the asymmetry stayed invisible: `GatewayRunner` worked for eight platforms and silently did nothing
|
|
41
|
+
for LINE and WhatsApp Cloud, whose payloads arrive on an HTTP route the application owns. Every app
|
|
42
|
+
wired those two by hand, beside the runner rather than through it.
|
|
43
|
+
|
|
44
|
+
```ts
|
|
45
|
+
const outcome = await adapter.deliver(event); // "ok" | "no_handler" | "handler_threw"
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
The three outcomes are distinguished because a caller acts on them differently: answering a webhook
|
|
49
|
+
200 when nobody was subscribed tells the provider to stop retrying a message nothing received.
|
|
50
|
+
|
|
51
|
+
`BasePlatformAdapter.runHandler` holds the containment once, where ten copies of it used to live —
|
|
52
|
+
a handler is user code, its throw is named as the handler's failure rather than the platform's, and
|
|
53
|
+
delivery continues. Each adapter's `deliver` is one line over it.
|
|
54
|
+
|
|
55
|
+
Also: `gateway-sms`'s `createWebhookServer` now signs against the configured `publicUrl` (#90).
|
|
56
|
+
Twilio verifies against the URL it POSTed to, and behind a proxy that rewrites `host` — a tunnel, an
|
|
57
|
+
ingress, a load balancer terminating TLS — the reconstruction from headers yields the internal
|
|
58
|
+
address, so a correct signature fails on every delivery. `publicUrl` is required by all three
|
|
59
|
+
backend option shapes and documented as "used by signature verifier"; until now no source file read
|
|
60
|
+
it. The header reconstruction stays as the fallback for an app served directly.
|
|
61
|
+
|
|
62
|
+
- 6f5948c: `smsWebhookVerifier(adapter)` — serve an SMS webhook through a framework channel seam.
|
|
63
|
+
|
|
64
|
+
A webhook seam takes a map of validators, and there was no way to put SMS in one. Twilio signs the
|
|
65
|
+
URL plus the sorted POST parameters, Plivo signs a different string, and Vonage uses a JWT — three
|
|
66
|
+
schemes that already live in this package with their own tests. Reimplementing them in the
|
|
67
|
+
framework would put security-critical code in two repositories and guarantee they drift, so the
|
|
68
|
+
direction is inverted: the framework declares the shape, and the package that owns the platform
|
|
69
|
+
provides the implementation.
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
await handleChannelWebhook(request, pathname, {
|
|
73
|
+
validators: { sms: smsWebhookVerifier(adapter) },
|
|
74
|
+
});
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Nothing new is depended on. The return type is structural, declared here as `WebhookVerifyResult`.
|
|
78
|
+
|
|
79
|
+
**`SMSAdapter.publicUrl` is now public, and now does something.** All three backend option shapes
|
|
80
|
+
require it and document it as "used by signature verifier" — and no source file read it: it appeared
|
|
81
|
+
only in the type and in test fixtures. Twilio SIGNS that URL, so it matters most in exactly the case
|
|
82
|
+
the request cannot cover: behind a proxy or a tunnel, the request's own URL is the internal one and
|
|
83
|
+
will not match what was signed. The verifier uses it.
|
|
84
|
+
|
|
85
|
+
One behaviour worth knowing before wiring this: **connect the adapter first.** Each backend loads
|
|
86
|
+
its provider SDK during `connect()`, and until then `verifySignature` answers `false` for
|
|
87
|
+
everything — so a verifier wired earlier refuses every genuine delivery as a bad signature. The two
|
|
88
|
+
are not distinguishable through the backend contract, which returns a boolean; the behaviour is
|
|
89
|
+
pinned by a test rather than papered over.
|
|
90
|
+
|
|
91
|
+
### Patch Changes
|
|
92
|
+
|
|
93
|
+
- 4b1d4bb: The half of an Express webhook server that is the same everywhere now lives in one place (#89).
|
|
94
|
+
|
|
95
|
+
`gateway-line` and `gateway-sms` each shipped one and shared 101 of ~170 lines: the lazy `express`
|
|
96
|
+
load, the raw-body capture with the hang it documents, and the start/stop lifecycle. What differs —
|
|
97
|
+
signature verification, body parsing, routing — stayed where it belongs.
|
|
98
|
+
|
|
99
|
+
It had already been paid for. A write-once latch made `start()` after `stop()` return without
|
|
100
|
+
creating a listener, which is a port nothing answers on with no error and no log, and the fix had to
|
|
101
|
+
be applied to both files by one commit because the latch lived in the copied half.
|
|
102
|
+
|
|
103
|
+
`@theokit/gateway` now exports `loadPeer`, `rawBodyCapture` and `listenerLifecycle`. **This does not
|
|
104
|
+
make express a dependency of the core**: nothing in that module imports it. Every shape is
|
|
105
|
+
structural — a request is whatever has `readableEnded` and `on`, a listener is whatever has `listen`
|
|
106
|
+
and `close` — so the two packages that use express keep declaring it and the core never learns the
|
|
107
|
+
name.
|
|
108
|
+
|
|
109
|
+
Every adapter README now states how inbound reaches it (#91): a webhook the application must
|
|
110
|
+
authenticate, a WebSocket, a sync loop, or an SDK that owns its own HTTP server. The three that have
|
|
111
|
+
no webhook say so with the reason, because an absence that is a decision should not read as a gap.
|
|
112
|
+
|
|
3
113
|
## 0.2.3
|
|
4
114
|
|
|
5
115
|
### Patch Changes
|
package/README.md
CHANGED
|
@@ -10,6 +10,19 @@ Three backends, opt-in via peer-dep:
|
|
|
10
10
|
| Plivo | `plivo` | `X-Plivo-Signature-V3` (HMAC-SHA256) |
|
|
11
11
|
| Vonage | `@vonage/server-sdk` | `Authorization: Bearer <JWT>` |
|
|
12
12
|
|
|
13
|
+
|
|
14
|
+
## How inbound arrives
|
|
15
|
+
|
|
16
|
+
**HTTP webhook**, and the application must authenticate it. Each provider signs differently —
|
|
17
|
+
Twilio over the URL plus the sorted POST parameters, Plivo over another string, Vonage with a JWT —
|
|
18
|
+
so the verification lives here rather than in a framework that would have to reimplement all three.
|
|
19
|
+
|
|
20
|
+
Two ways to serve it. `createWebhookServer` mounts the Express routes for you; or host the route
|
|
21
|
+
yourself and pass `smsWebhookVerifier(adapter)` to a framework webhook seam.
|
|
22
|
+
|
|
23
|
+
Set `publicUrl` to the address the provider posts to. Twilio SIGNS that URL, and behind a proxy that
|
|
24
|
+
rewrites `host` — a tunnel, an ingress, a load balancer terminating TLS — the address the request
|
|
25
|
+
arrived on is the internal one and every genuine delivery fails its signature.
|
|
13
26
|
## Install
|
|
14
27
|
|
|
15
28
|
```bash
|
package/dist/index.cjs
CHANGED
|
@@ -446,6 +446,18 @@ var SMSAdapter = class extends gateway.BasePlatformAdapter {
|
|
|
446
446
|
);
|
|
447
447
|
}
|
|
448
448
|
platform = "sms";
|
|
449
|
+
/**
|
|
450
|
+
* The URL the provider POSTs inbound to, as the provider sees it.
|
|
451
|
+
*
|
|
452
|
+
* Required by all three backend option shapes and documented there as "used by signature
|
|
453
|
+
* verifier" — and, measured 2026-08-31, read by nothing: it appeared only in the type and in test
|
|
454
|
+
* fixtures. Twilio SIGNS this URL, so the value matters most in exactly the case where the
|
|
455
|
+
* request cannot supply it: behind a proxy or a tunnel, the request's own URL is the internal one
|
|
456
|
+
* and will not match what was signed.
|
|
457
|
+
*
|
|
458
|
+
* Exposed so {@link smsWebhookVerifier} can use it, which is what makes the option true.
|
|
459
|
+
*/
|
|
460
|
+
publicUrl;
|
|
449
461
|
backend;
|
|
450
462
|
inboundHandler;
|
|
451
463
|
connected = false;
|
|
@@ -460,6 +472,7 @@ var SMSAdapter = class extends gateway.BasePlatformAdapter {
|
|
|
460
472
|
});
|
|
461
473
|
}
|
|
462
474
|
this.defaultCountry = opts.defaultCountry;
|
|
475
|
+
this.publicUrl = opts.publicUrl;
|
|
463
476
|
this.backend = createBackend(opts);
|
|
464
477
|
}
|
|
465
478
|
async connect() {
|
|
@@ -578,6 +591,15 @@ var SMSAdapter = class extends gateway.BasePlatformAdapter {
|
|
|
578
591
|
getBackendKind() {
|
|
579
592
|
return this.backend.kind;
|
|
580
593
|
}
|
|
594
|
+
/**
|
|
595
|
+
* Deliver an event that arrived out of band — the ingest `onInbound` had no counterpart for (#83).
|
|
596
|
+
*
|
|
597
|
+
* One line over `runHandler`, which owns the containment: a handler is user code, its throw is
|
|
598
|
+
* named as the handler's failure rather than the platform's, and delivery continues.
|
|
599
|
+
*/
|
|
600
|
+
async deliver(event) {
|
|
601
|
+
return this.runHandler(this.inboundHandler, event);
|
|
602
|
+
}
|
|
581
603
|
};
|
|
582
604
|
function secretFromOpts(opts) {
|
|
583
605
|
switch (opts.backend) {
|
|
@@ -605,59 +627,39 @@ function parseInbound(options, ctx) {
|
|
|
605
627
|
if (inbound.messageId === "") return null;
|
|
606
628
|
return inboundToMessageEvent(inbound, options.backend);
|
|
607
629
|
}
|
|
608
|
-
|
|
609
|
-
// src/webhook-server.ts
|
|
610
630
|
async function loadExpress() {
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
|
|
617
|
-
|
|
618
|
-
|
|
619
|
-
|
|
620
|
-
|
|
631
|
+
return gateway.loadPeer(
|
|
632
|
+
async () => import('express'),
|
|
633
|
+
() => {
|
|
634
|
+
throw new ConfigurationError({
|
|
635
|
+
code: "express_not_installed",
|
|
636
|
+
message: 'gateway-sms: peer-dep "express" not installed. Run: pnpm add express'
|
|
637
|
+
});
|
|
638
|
+
}
|
|
639
|
+
);
|
|
640
|
+
}
|
|
641
|
+
function signedUrl(req, headers, publicUrl) {
|
|
642
|
+
if (publicUrl !== void 0 && publicUrl !== "") return publicUrl;
|
|
643
|
+
const protoHeader = headers["x-forwarded-proto"];
|
|
644
|
+
const proto = protoHeader ?? (req.secure ? "https" : "http");
|
|
645
|
+
const host = req.get("host") ?? "localhost";
|
|
646
|
+
return `${proto}://${host}${req.originalUrl}`;
|
|
621
647
|
}
|
|
622
|
-
function buildSignatureContext(req) {
|
|
648
|
+
function buildSignatureContext(req, publicUrl) {
|
|
623
649
|
const rawBody = req.rawBody ?? "";
|
|
624
650
|
const headers = {};
|
|
625
651
|
for (const [k, v] of Object.entries(req.headers)) {
|
|
626
652
|
headers[k.toLowerCase()] = Array.isArray(v) ? v.join(",") : v ?? "";
|
|
627
653
|
}
|
|
628
|
-
|
|
629
|
-
const proto = protoHeader ?? (req.secure ? "https" : "http");
|
|
630
|
-
const host = req.get("host") ?? "localhost";
|
|
631
|
-
const url = `${proto}://${host}${req.originalUrl}`;
|
|
632
|
-
return { headers, rawBody, url };
|
|
654
|
+
return { headers, rawBody, url: signedUrl(req, headers, publicUrl) };
|
|
633
655
|
}
|
|
634
656
|
async function createWebhookServer(opts) {
|
|
635
|
-
const
|
|
636
|
-
const app = opts.app ??
|
|
657
|
+
const createApp = await loadExpress();
|
|
658
|
+
const app = opts.app ?? createApp();
|
|
637
659
|
const prefix = opts.path ?? "/sms";
|
|
638
660
|
const backend = opts.adapter.getBackendKind();
|
|
639
|
-
const rawCapture = (req, _res, next) => {
|
|
640
|
-
if (req.readableEnded || req.complete) {
|
|
641
|
-
process.stderr.write(
|
|
642
|
-
"[gateway-sms] raw body already consumed before signature capture \u2014 mount this router BEFORE any global body parser, or signature verification cannot see the bytes it must hash\n"
|
|
643
|
-
);
|
|
644
|
-
req.rawBody = "";
|
|
645
|
-
next();
|
|
646
|
-
return;
|
|
647
|
-
}
|
|
648
|
-
let buf = "";
|
|
649
|
-
req.setEncoding("utf8");
|
|
650
|
-
req.on("data", (chunk) => {
|
|
651
|
-
buf += chunk;
|
|
652
|
-
});
|
|
653
|
-
req.on("end", () => {
|
|
654
|
-
req.rawBody = buf;
|
|
655
|
-
next();
|
|
656
|
-
});
|
|
657
|
-
req.on("error", (err) => next(err));
|
|
658
|
-
};
|
|
659
661
|
const handler = (req, res) => {
|
|
660
|
-
const ctx = buildSignatureContext(req);
|
|
662
|
+
const ctx = buildSignatureContext(req, opts.adapter.publicUrl);
|
|
661
663
|
if (!opts.adapter.verifySignature(ctx)) {
|
|
662
664
|
res.status(401).type("text/plain").send("invalid signature");
|
|
663
665
|
return;
|
|
@@ -677,33 +679,27 @@ async function createWebhookServer(opts) {
|
|
|
677
679
|
});
|
|
678
680
|
res.status(204).end();
|
|
679
681
|
};
|
|
680
|
-
app.post(`${prefix}/${backend}`,
|
|
681
|
-
|
|
682
|
-
|
|
683
|
-
|
|
684
|
-
|
|
685
|
-
|
|
686
|
-
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
|
|
693
|
-
|
|
694
|
-
|
|
695
|
-
|
|
696
|
-
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
if (server === void 0) return;
|
|
702
|
-
await new Promise((resolve) => {
|
|
703
|
-
server?.close(() => resolve());
|
|
704
|
-
});
|
|
705
|
-
server = void 0;
|
|
706
|
-
}
|
|
682
|
+
app.post(`${prefix}/${backend}`, gateway.rawBodyCapture("gateway-sms"), handler);
|
|
683
|
+
return gateway.listenerLifecycle({ app, port: opts.port ?? 3e3, injected: opts.app !== void 0 });
|
|
684
|
+
}
|
|
685
|
+
|
|
686
|
+
// src/webhook-verifier.ts
|
|
687
|
+
function headersOf(request) {
|
|
688
|
+
const out = {};
|
|
689
|
+
request.headers.forEach((value, key) => {
|
|
690
|
+
out[key] = value;
|
|
691
|
+
});
|
|
692
|
+
return out;
|
|
693
|
+
}
|
|
694
|
+
function smsWebhookVerifier(adapter, opts = {}) {
|
|
695
|
+
return async (request) => {
|
|
696
|
+
const rawBody = await request.text();
|
|
697
|
+
const ctx = {
|
|
698
|
+
headers: headersOf(request),
|
|
699
|
+
rawBody,
|
|
700
|
+
url: opts.publicUrl ?? adapter.publicUrl ?? request.url
|
|
701
|
+
};
|
|
702
|
+
return adapter.verifySignature(ctx) ? { ok: true } : { ok: false, reason: "signature mismatch" };
|
|
707
703
|
};
|
|
708
704
|
}
|
|
709
705
|
|
|
@@ -713,6 +709,7 @@ exports.SMSAdapter = SMSAdapter;
|
|
|
713
709
|
exports.createWebhookServer = createWebhookServer;
|
|
714
710
|
exports.normalizeE164 = normalizeE164;
|
|
715
711
|
exports.parseInbound = parseInbound;
|
|
712
|
+
exports.smsWebhookVerifier = smsWebhookVerifier;
|
|
716
713
|
exports.splitForSMS = splitForSMS;
|
|
717
714
|
//# sourceMappingURL=index.cjs.map
|
|
718
715
|
//# sourceMappingURL=index.cjs.map
|