@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 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(options, ctx) {
638
- const backend = createBackend(options);
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, options.backend);
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
- let pairs;
677
- try {
678
- pairs = parseForm(await request.text());
679
- } catch {
680
- return { ok: false, reason: "unparseable body" };
681
- }
682
- const expected = Buffer.from(sign(opts.authToken, opts.publicUrl ?? request.url, pairs));
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;