@theokit/gateway-sms 0.5.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 CHANGED
@@ -1,5 +1,11 @@
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
+
3
9
  ## 0.5.0
4
10
 
5
11
  ### Minor Changes
package/README.md CHANGED
@@ -158,5 +158,20 @@ const { adapters, rejected } = createChannels([{ descriptor: smsChannel, config
158
158
  | `publicUrl` | `SMS_PUBLIC_URL` | yes | no |
159
159
 
160
160
  `create` throws `ConfigurationError` (`invalid_config`) naming the key for a missing or non-string
161
- value. The descriptor declares `transport: "socket"`; inbound messages still arrive through a
162
- webhook you host (`createWebhookServer`), which this descriptor does not set up.
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) {
@@ -633,6 +651,128 @@ function secretFromOpts(opts) {
633
651
  }
634
652
  }
635
653
 
654
+ // src/parse-inbound.ts
655
+ function parseInbound(options2, ctx) {
656
+ const backend = createBackend(options2);
657
+ let inbound;
658
+ try {
659
+ inbound = backend.parseInbound(ctx);
660
+ } catch {
661
+ return null;
662
+ }
663
+ if (inbound.messageId === "") return null;
664
+ return inboundToMessageEvent(inbound, options2.backend);
665
+ }
666
+ function decode(s) {
667
+ return decodeURIComponent(s.replace(/\+/g, " "));
668
+ }
669
+ function parseForm(body) {
670
+ const out = [];
671
+ for (const pair of body.split("&")) {
672
+ if (pair.length === 0) continue;
673
+ const eq = pair.indexOf("=");
674
+ out.push([decode(eq < 0 ? pair : pair.slice(0, eq)), decode(eq < 0 ? "" : pair.slice(eq + 1))]);
675
+ }
676
+ return out;
677
+ }
678
+ function compare(a, b) {
679
+ if (a === b) return 0;
680
+ return a < b ? -1 : 1;
681
+ }
682
+ function sign(authToken, url, pairs) {
683
+ const sorted = [...pairs].sort((x, y) => compare(x[0], y[0]) || compare(x[1], y[1]));
684
+ let data = url;
685
+ for (const [k, v] of sorted) data += k + v;
686
+ return crypto.createHmac("sha1", authToken).update(data, "utf8").digest("base64");
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
+ }
700
+ function twilioRequestVerifier(opts) {
701
+ return async (request) => {
702
+ const header = request.headers.get("x-twilio-signature");
703
+ if (header === null || header.length === 0) {
704
+ return { ok: false, reason: "missing X-Twilio-Signature header" };
705
+ }
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" };
713
+ return { ok: true };
714
+ };
715
+ }
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
+
636
776
  // src/channel.ts
637
777
  var KEYS = ["accountSid", "authToken", "fromNumber", "publicUrl"];
638
778
  function readString(config, key) {
@@ -678,75 +818,24 @@ var CONFIG = [
678
818
  ];
679
819
  var smsChannel = {
680
820
  platform: "sms",
681
- transport: "socket",
821
+ transport: "webhook",
822
+ webhook: twilioWebhook,
682
823
  config: CONFIG,
683
824
  create(config) {
684
825
  const [accountSid, authToken, fromNumber, publicUrl] = KEYS.map((k) => readString(config, k));
685
- return new SMSAdapter({
826
+ const opts = {
686
827
  backend: "twilio",
687
828
  accountSid,
688
829
  authToken,
689
830
  fromNumber,
690
831
  publicUrl
691
- });
832
+ };
833
+ const adapter = new SMSAdapter(opts);
834
+ rememberSmsOptions(adapter, opts);
835
+ return adapter;
692
836
  }
693
837
  };
694
838
 
695
- // src/parse-inbound.ts
696
- function parseInbound(options, ctx) {
697
- const backend = createBackend(options);
698
- let inbound;
699
- try {
700
- inbound = backend.parseInbound(ctx);
701
- } catch {
702
- return null;
703
- }
704
- if (inbound.messageId === "") return null;
705
- return inboundToMessageEvent(inbound, options.backend);
706
- }
707
- function decode(s) {
708
- return decodeURIComponent(s.replace(/\+/g, " "));
709
- }
710
- function parseForm(body) {
711
- const out = [];
712
- for (const pair of body.split("&")) {
713
- if (pair.length === 0) continue;
714
- const eq = pair.indexOf("=");
715
- out.push([decode(eq < 0 ? pair : pair.slice(0, eq)), decode(eq < 0 ? "" : pair.slice(eq + 1))]);
716
- }
717
- return out;
718
- }
719
- function compare(a, b) {
720
- if (a === b) return 0;
721
- return a < b ? -1 : 1;
722
- }
723
- function sign(authToken, url, pairs) {
724
- const sorted = [...pairs].sort((x, y) => compare(x[0], y[0]) || compare(x[1], y[1]));
725
- let data = url;
726
- for (const [k, v] of sorted) data += k + v;
727
- return crypto.createHmac("sha1", authToken).update(data, "utf8").digest("base64");
728
- }
729
- function twilioRequestVerifier(opts) {
730
- return async (request) => {
731
- const header = request.headers.get("x-twilio-signature");
732
- if (header === null || header.length === 0) {
733
- return { ok: false, reason: "missing X-Twilio-Signature header" };
734
- }
735
- let pairs;
736
- try {
737
- pairs = parseForm(await request.text());
738
- } catch {
739
- return { ok: false, reason: "unparseable body" };
740
- }
741
- const expected = Buffer.from(sign(opts.authToken, opts.publicUrl ?? request.url, pairs));
742
- const actual = Buffer.from(header);
743
- if (expected.length !== actual.length || !crypto.timingSafeEqual(expected, actual)) {
744
- return { ok: false, reason: "signature mismatch" };
745
- }
746
- return { ok: true };
747
- };
748
- }
749
-
750
839
  // src/twiml.ts
751
840
  var ILLEGAL = /[\u0000-\u0008\u000B\u000C\u000E-\u001F￾￿]/g;
752
841
  function esc(s) {