@theokit/gateway-sms 0.4.0 → 0.6.0
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 +12 -0
- package/README.md +39 -0
- package/dist/index.cjs +163 -14
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +53 -1
- package/dist/index.d.ts +53 -1
- package/dist/index.js +163 -15
- package/dist/index.js.map +1 -1
- package/package.json +3 -3
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,17 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.6.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 3158f63: The `whatsappChannel` Cloud variant and `smsChannel` descriptors now declare `transport: "webhook"` with a `webhook.handle`, so a host mounts them with `createWebhookHandler`. WhatsApp answers Meta's subscription check and verifies `x-hub-signature-256`; SMS verifies Twilio's signature against the configured `publicUrl`. The Express listeners are unchanged.
|
|
8
|
+
|
|
9
|
+
## 0.5.0
|
|
10
|
+
|
|
11
|
+
### Minor Changes
|
|
12
|
+
|
|
13
|
+
- 2d91e29: Ship `tlonUrbitChannel` and `smsChannel` (Twilio) `ChannelDescriptor`s with env bindings for `createChannels` and `configFromEnv`.
|
|
14
|
+
|
|
3
15
|
## 0.4.0
|
|
4
16
|
|
|
5
17
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -136,3 +136,42 @@ The live smoke sends one real SMS through Twilio's API (test creds work; they co
|
|
|
136
136
|
## ADRs
|
|
137
137
|
|
|
138
138
|
D389 – D396 in `.claude/knowledge-base/adrs/`.
|
|
139
|
+
|
|
140
|
+
## Channel descriptor
|
|
141
|
+
|
|
142
|
+
`smsChannel` is a `ChannelDescriptor` for `createChannels` and `configFromEnv`. It builds the
|
|
143
|
+
Twilio backend only; use `new SMSAdapter(...)` directly for Plivo, Vonage or `defaultCountry`.
|
|
144
|
+
|
|
145
|
+
```typescript
|
|
146
|
+
import { configFromEnv, createChannels } from "@theokit/gateway";
|
|
147
|
+
import { smsChannel } from "@theokit/gateway-sms";
|
|
148
|
+
|
|
149
|
+
const { config, missing } = configFromEnv(smsChannel, process.env, "APP_");
|
|
150
|
+
const { adapters, rejected } = createChannels([{ descriptor: smsChannel, config }]);
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
| Key | Env name | Required | Secret |
|
|
154
|
+
| --- | --- | --- | --- |
|
|
155
|
+
| `accountSid` | `SMS_ACCOUNT_SID` | yes | no |
|
|
156
|
+
| `authToken` | `SMS_AUTH_TOKEN` | yes | yes |
|
|
157
|
+
| `fromNumber` | `SMS_FROM_NUMBER` | yes | no |
|
|
158
|
+
| `publicUrl` | `SMS_PUBLIC_URL` | yes | no |
|
|
159
|
+
|
|
160
|
+
`create` throws `ConfigurationError` (`invalid_config`) naming the key for a missing or non-string
|
|
161
|
+
value. The descriptor declares `transport: "webhook"`; `createWebhookServer` (Express) keeps working.
|
|
162
|
+
|
|
163
|
+
### Mounting the route
|
|
164
|
+
|
|
165
|
+
`webhook.handle` verifies `X-Twilio-Signature` against the configured `publicUrl` (never the
|
|
166
|
+
request's Host header), answers 401 on a bad signature, 400 when the form body holds no message,
|
|
167
|
+
and otherwise delivers and answers 200 (500 or 503 when the handler threw or none is subscribed).
|
|
168
|
+
|
|
169
|
+
```ts
|
|
170
|
+
import { createChannels, createWebhookHandler } from "@theokit/gateway";
|
|
171
|
+
import { smsChannel } from "@theokit/gateway-sms";
|
|
172
|
+
|
|
173
|
+
const { channels } = createChannels([{ descriptor: smsChannel, config }]);
|
|
174
|
+
const handle = createWebhookHandler({ channels, isStarted: () => true });
|
|
175
|
+
// POST /webhooks/sms -> handle(request)
|
|
176
|
+
```
|
|
177
|
+
|
package/dist/index.cjs
CHANGED
|
@@ -618,6 +618,24 @@ var SMSAdapter = class extends gateway.BasePlatformAdapter {
|
|
|
618
618
|
async deliver(event) {
|
|
619
619
|
return this.runHandler(this.inboundHandler, event);
|
|
620
620
|
}
|
|
621
|
+
/**
|
|
622
|
+
* Deliver like {@link deliver}, but a throwing handler is logged by name only: its message can
|
|
623
|
+
* carry the inbound text, which the webhook route must not write to a log line.
|
|
624
|
+
*
|
|
625
|
+
* @internal
|
|
626
|
+
*/
|
|
627
|
+
async deliverQuietly(event) {
|
|
628
|
+
const handler = this.inboundHandler;
|
|
629
|
+
if (handler === void 0) return "no_handler";
|
|
630
|
+
try {
|
|
631
|
+
await handler(event);
|
|
632
|
+
} catch {
|
|
633
|
+
process.stderr.write(`[sms] handler threw
|
|
634
|
+
`);
|
|
635
|
+
return "handler_threw";
|
|
636
|
+
}
|
|
637
|
+
return "ok";
|
|
638
|
+
}
|
|
621
639
|
};
|
|
622
640
|
function secretFromOpts(opts) {
|
|
623
641
|
switch (opts.backend) {
|
|
@@ -634,8 +652,8 @@ function secretFromOpts(opts) {
|
|
|
634
652
|
}
|
|
635
653
|
|
|
636
654
|
// src/parse-inbound.ts
|
|
637
|
-
function parseInbound(
|
|
638
|
-
const backend = createBackend(
|
|
655
|
+
function parseInbound(options2, ctx) {
|
|
656
|
+
const backend = createBackend(options2);
|
|
639
657
|
let inbound;
|
|
640
658
|
try {
|
|
641
659
|
inbound = backend.parseInbound(ctx);
|
|
@@ -643,7 +661,7 @@ function parseInbound(options, ctx) {
|
|
|
643
661
|
return null;
|
|
644
662
|
}
|
|
645
663
|
if (inbound.messageId === "") return null;
|
|
646
|
-
return inboundToMessageEvent(inbound,
|
|
664
|
+
return inboundToMessageEvent(inbound, options2.backend);
|
|
647
665
|
}
|
|
648
666
|
function decode(s) {
|
|
649
667
|
return decodeURIComponent(s.replace(/\+/g, " "));
|
|
@@ -667,27 +685,157 @@ function sign(authToken, url, pairs) {
|
|
|
667
685
|
for (const [k, v] of sorted) data += k + v;
|
|
668
686
|
return crypto.createHmac("sha1", authToken).update(data, "utf8").digest("base64");
|
|
669
687
|
}
|
|
688
|
+
function verifyTwilioSignature(authToken, url, rawBody, signature) {
|
|
689
|
+
if (signature === void 0 || signature.length === 0) return false;
|
|
690
|
+
let pairs;
|
|
691
|
+
try {
|
|
692
|
+
pairs = parseForm(rawBody);
|
|
693
|
+
} catch {
|
|
694
|
+
return false;
|
|
695
|
+
}
|
|
696
|
+
const expected = Buffer.from(sign(authToken, url, pairs));
|
|
697
|
+
const actual = Buffer.from(signature);
|
|
698
|
+
return expected.length === actual.length && crypto.timingSafeEqual(expected, actual);
|
|
699
|
+
}
|
|
670
700
|
function twilioRequestVerifier(opts) {
|
|
671
701
|
return async (request) => {
|
|
672
702
|
const header = request.headers.get("x-twilio-signature");
|
|
673
703
|
if (header === null || header.length === 0) {
|
|
674
704
|
return { ok: false, reason: "missing X-Twilio-Signature header" };
|
|
675
705
|
}
|
|
676
|
-
|
|
677
|
-
|
|
678
|
-
|
|
679
|
-
|
|
680
|
-
|
|
681
|
-
|
|
682
|
-
|
|
683
|
-
const actual = Buffer.from(header);
|
|
684
|
-
if (expected.length !== actual.length || !crypto.timingSafeEqual(expected, actual)) {
|
|
685
|
-
return { ok: false, reason: "signature mismatch" };
|
|
686
|
-
}
|
|
706
|
+
const ok = verifyTwilioSignature(
|
|
707
|
+
opts.authToken,
|
|
708
|
+
opts.publicUrl ?? request.url,
|
|
709
|
+
await request.text(),
|
|
710
|
+
header
|
|
711
|
+
);
|
|
712
|
+
if (!ok) return { ok: false, reason: "signature mismatch" };
|
|
687
713
|
return { ok: true };
|
|
688
714
|
};
|
|
689
715
|
}
|
|
690
716
|
|
|
717
|
+
// src/fetch-webhook.ts
|
|
718
|
+
var options = /* @__PURE__ */ new WeakMap();
|
|
719
|
+
function rememberSmsOptions(adapter, opts) {
|
|
720
|
+
options.set(adapter, opts);
|
|
721
|
+
}
|
|
722
|
+
function statusFor(outcomes) {
|
|
723
|
+
let status = 200;
|
|
724
|
+
for (const outcome of outcomes) {
|
|
725
|
+
if (outcome === "handler_threw") status = 500;
|
|
726
|
+
else if (outcome === "no_handler" && status === 200) status = 503;
|
|
727
|
+
}
|
|
728
|
+
return status;
|
|
729
|
+
}
|
|
730
|
+
function lowerHeaders(headers) {
|
|
731
|
+
const out = {};
|
|
732
|
+
for (const [key, value] of Object.entries(headers)) {
|
|
733
|
+
if (value !== void 0) out[key.toLowerCase()] = value;
|
|
734
|
+
}
|
|
735
|
+
return out;
|
|
736
|
+
}
|
|
737
|
+
function verified(opts, request) {
|
|
738
|
+
if (opts === void 0 || opts.authToken.trim().length === 0) return false;
|
|
739
|
+
return verifyTwilioSignature(
|
|
740
|
+
opts.authToken,
|
|
741
|
+
opts.publicUrl,
|
|
742
|
+
request.rawBody,
|
|
743
|
+
lowerHeaders(request.headers)["x-twilio-signature"]
|
|
744
|
+
);
|
|
745
|
+
}
|
|
746
|
+
function toEvent(opts, rawBody, headers) {
|
|
747
|
+
return parseInbound(opts, { headers, rawBody, url: opts.publicUrl });
|
|
748
|
+
}
|
|
749
|
+
var twilioWebhook = {
|
|
750
|
+
methods: ["POST"],
|
|
751
|
+
/** The same check `handle` makes; needs no connection. */
|
|
752
|
+
verify(adapter, request) {
|
|
753
|
+
return verified(options.get(adapter), request);
|
|
754
|
+
},
|
|
755
|
+
/** A payload of form fields (as an object) is parsed like the form body and delivered. */
|
|
756
|
+
async ingest(adapter, payload) {
|
|
757
|
+
const opts = options.get(adapter);
|
|
758
|
+
if (opts === void 0 || payload === null || typeof payload !== "object") return "malformed";
|
|
759
|
+
const form = new URLSearchParams();
|
|
760
|
+
for (const [key, value] of Object.entries(payload)) {
|
|
761
|
+
if (typeof value === "string") form.set(key, value);
|
|
762
|
+
}
|
|
763
|
+
const event = toEvent(opts, form.toString(), {});
|
|
764
|
+
if (event === null) return "malformed";
|
|
765
|
+
return statusFor([await adapter.deliverQuietly(event)]) === 200 ? "delivered" : "no_handler";
|
|
766
|
+
},
|
|
767
|
+
async handle(adapter, request) {
|
|
768
|
+
const opts = options.get(adapter);
|
|
769
|
+
if (opts === void 0 || !verified(opts, request)) return { status: 401 };
|
|
770
|
+
const event = toEvent(opts, request.rawBody, lowerHeaders(request.headers));
|
|
771
|
+
if (event === null) return { status: 400 };
|
|
772
|
+
return { status: statusFor([await adapter.deliverQuietly(event)]) };
|
|
773
|
+
}
|
|
774
|
+
};
|
|
775
|
+
|
|
776
|
+
// src/channel.ts
|
|
777
|
+
var KEYS = ["accountSid", "authToken", "fromNumber", "publicUrl"];
|
|
778
|
+
function readString(config, key) {
|
|
779
|
+
const value = config[key];
|
|
780
|
+
if (typeof value !== "string" || value.trim().length === 0) {
|
|
781
|
+
throw new ConfigurationError({
|
|
782
|
+
code: "invalid_config",
|
|
783
|
+
message: `gateway-sms: config.${key} must be a non-empty string`,
|
|
784
|
+
detail: key
|
|
785
|
+
});
|
|
786
|
+
}
|
|
787
|
+
return value;
|
|
788
|
+
}
|
|
789
|
+
var CONFIG = [
|
|
790
|
+
{
|
|
791
|
+
key: "accountSid",
|
|
792
|
+
required: true,
|
|
793
|
+
secret: false,
|
|
794
|
+
env: "SMS_ACCOUNT_SID",
|
|
795
|
+
description: "The Twilio account SID."
|
|
796
|
+
},
|
|
797
|
+
{
|
|
798
|
+
key: "authToken",
|
|
799
|
+
required: true,
|
|
800
|
+
secret: true,
|
|
801
|
+
env: "SMS_AUTH_TOKEN",
|
|
802
|
+
description: "The Twilio auth token; also verifies inbound signatures."
|
|
803
|
+
},
|
|
804
|
+
{
|
|
805
|
+
key: "fromNumber",
|
|
806
|
+
required: true,
|
|
807
|
+
secret: false,
|
|
808
|
+
env: "SMS_FROM_NUMBER",
|
|
809
|
+
description: "The bot's own E.164 number, used as the sender."
|
|
810
|
+
},
|
|
811
|
+
{
|
|
812
|
+
key: "publicUrl",
|
|
813
|
+
required: true,
|
|
814
|
+
secret: false,
|
|
815
|
+
env: "SMS_PUBLIC_URL",
|
|
816
|
+
description: "The public URL Twilio posts inbound messages to."
|
|
817
|
+
}
|
|
818
|
+
];
|
|
819
|
+
var smsChannel = {
|
|
820
|
+
platform: "sms",
|
|
821
|
+
transport: "webhook",
|
|
822
|
+
webhook: twilioWebhook,
|
|
823
|
+
config: CONFIG,
|
|
824
|
+
create(config) {
|
|
825
|
+
const [accountSid, authToken, fromNumber, publicUrl] = KEYS.map((k) => readString(config, k));
|
|
826
|
+
const opts = {
|
|
827
|
+
backend: "twilio",
|
|
828
|
+
accountSid,
|
|
829
|
+
authToken,
|
|
830
|
+
fromNumber,
|
|
831
|
+
publicUrl
|
|
832
|
+
};
|
|
833
|
+
const adapter = new SMSAdapter(opts);
|
|
834
|
+
rememberSmsOptions(adapter, opts);
|
|
835
|
+
return adapter;
|
|
836
|
+
}
|
|
837
|
+
};
|
|
838
|
+
|
|
691
839
|
// src/twiml.ts
|
|
692
840
|
var ILLEGAL = /[\u0000-\u0008\u000B\u000C\u000E-\u001F]/g;
|
|
693
841
|
function esc(s) {
|
|
@@ -805,6 +953,7 @@ exports.SMSAdapter = SMSAdapter;
|
|
|
805
953
|
exports.createWebhookServer = createWebhookServer;
|
|
806
954
|
exports.normalizeE164 = normalizeE164;
|
|
807
955
|
exports.parseInbound = parseInbound;
|
|
956
|
+
exports.smsChannel = smsChannel;
|
|
808
957
|
exports.smsWebhookVerifier = smsWebhookVerifier;
|
|
809
958
|
exports.splitForSMS = splitForSMS;
|
|
810
959
|
exports.twilioRequestVerifier = twilioRequestVerifier;
|