@drawbridge/drawbridge-utils 0.0.125 → 0.0.126

package/dist/connections/index.d.ts

@@ -1,9 +1,9 @@
 import { authToken } from './oauth.js';
 export { consentUrl, pkcePair } from './oauth.js';
 import { toE164, detectCountry } from '../phone.js';
+import crypto, { createHmac, timingSafeEqual, createHash, randomUUID } from 'node:crypto';
 import { request } from '../http.js';
 import { channels } from '../pricing.js';
-import crypto, { createHash, createHmac, timingSafeEqual, randomUUID } from 'node:crypto';
 import { customAlphabet } from 'nanoid';
 import { toCanonicalEmail } from '../email.js';
 import { conversionRate } from '../plans.js';
@@ -282,7 +282,7 @@ const HOOK_EFFECTS = Object.freeze([ 'enqueues', 'events', 'writes' ]);
 // The controller methods a described write may become. Only the two that a hook
 // has ever needed — a deletion is a cascade, and cascades are owned by
 // drawbridge-sync's streams rather than by a step.
-const WRITE_OPERATIONS = Object.freeze([ 'create', 'update' ]);
+const WRITE_OPERATIONS = Object.freeze([ 'create', 'delete', 'update' ]);
 
 // READ A HOOK'S EFFECTS, or refuse them.
 //
@@ -414,13 +414,15 @@ const effectsOf = ( answer ) => {
 
 		}
 
-		if( ! write?.data ) throw new Error( 'A described write on ' + write.collection + ' carries no data' );
+		// A delete says WHICH, not WHAT — its query is its whole statement.
+		if( write.operation !== 'delete' && ! write?.data ) throw new Error( 'A described write on ' + write.collection + ' carries no data' );
 
-		// AN UPDATE WITH NO QUERY IS EVERY DOCUMENT IN THE COLLECTION. Refused here
-		// rather than survived, because the controller would happily run it.
-		if( write.operation === 'update' && ! write.query ){
+		// AN UPDATE OR DELETE WITH NO QUERY IS EVERY DOCUMENT IN THE COLLECTION.
+		// Refused here rather than survived, because the controller would happily
+		// run it.
+		if( [ 'delete', 'update' ].includes( write.operation ) && ! write.query ){
 
-			throw new Error( 'A described update on ' + write.collection + ' has no query — that is every document in it' );
+			throw new Error( 'A described ' + write.operation + ' on ' + write.collection + ' has no query — that is every document in it' );
 
 		}
 
@@ -1577,6 +1579,14 @@ var icon$3 = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xm
 </defs>
 </svg>`;
 
+// TWILIO'S OWN KEYWORD LISTS. STOP-family withdraws consent for the number —
+// platform-wide, because every organization sends from the same platform number,
+// so a withdrawal cannot be scoped narrower than the number it was sent to.
+// START-family re-subscribes. Anything else is a real reply and none of our
+// business.
+const STOP_KEYWORDS = [ 'STOP', 'STOPALL', 'UNSUBSCRIBE', 'CANCEL', 'END', 'QUIT' ];
+const START_KEYWORDS = [ 'START', 'UNSTOP', 'YES' ];
+
 // Drawbridge itself — the PRIVATE connection.
 //
 // Nobody connects this. There is no credential, no consent, and no card on the
@@ -1931,7 +1941,113 @@ var drawbridge = {
 			}
 
 		},
-		inbound : false,
+		// INBOUND SMS to the platform number. Twilio's webhook, verified and
+		// processed HERE — the manifest owns its own inbound, the same as every
+		// other vendor, and the bespoke webhooks route + the handler that lived in
+		// sync's buffer table are gone.
+		inbound : {
+
+			// EVERY POST ON THIS CHANNEL IS AN INBOUND MESSAGE. Twilio sends no
+			// topic header — the registered url IS the topic.
+			event : () => 'message.inbound',
+
+			// STOP AND START, AS DESCRIBED WRITES. A withdrawn number is withdrawn
+			// for everyone — organization : null is the platform floor canSend()
+			// reads on every send path. $setOnInsert + upsert so webhook replays
+			// and repeat STOPs collapse onto the unique { channel, address,
+			// organization } index instead of erroring.
+			process : ({ context }) => {
+
+				const keyword = String( context?.data?.Body || '' ).trim().toUpperCase();
+				const address = toE164( context?.data?.From );
+
+				if( ! address ) return { message : 'Inbound SMS carried no usable sender number.', skipped : true };
+
+				if( STOP_KEYWORDS.includes( keyword ) ){
+
+					return {
+						message : 'STOP recorded — ' + address + ' is suppressed on SMS everywhere.',
+						request : { keyword },
+						writes : [ {
+							collection : 'suppression',
+							data : {
+								$setOnInsert : {
+									address,
+									channel : 'sms',
+									organization : null,
+									reason : keyword,
+									source : 'stop'
+								}
+							},
+							operation : 'update',
+							options : { upsert : true },
+							query : {
+								address,
+								channel : 'sms',
+								organization : null
+							}
+						} ]
+					};
+
+				}
+
+				if( START_KEYWORDS.includes( keyword ) ){
+
+					return {
+						message : 'START recorded — ' + address + ' can receive SMS again.',
+						request : { keyword },
+						writes : [ {
+							collection : 'suppression',
+							operation : 'delete',
+							query : {
+								address,
+								channel : 'sms',
+								organization : null
+							}
+						} ]
+					};
+
+				}
+
+				return { message : 'A real reply, not a keyword — nothing to record.', skipped : true };
+
+			},
+
+			receive : ({ payload }) => ({
+				data : payload,
+				provider : { id : payload?.MessageSid || null }
+			}),
+
+			// TWILIO'S SCHEME, from docs.twilio.com/usage/security: take the full
+			// registered url, sort the POST parameters alphabetically (Unix-style,
+			// case-sensitive), append each name and value with no delimiters, sign
+			// with HMAC-SHA1 keyed by the AuthToken, base64 — compared against
+			// X-Twilio-Signature. It signs the URL rather than the raw body, which
+			// is exactly why the shared body-HMAC verifier cannot cover it and this
+			// hook exists.
+			verify : ({ body, headers, secret, url }) => {
+
+				// OUR misconfiguration, never a forgery — a missing credential must
+				// not be answered 401.
+				if( ! secret ) throw Object.assign( new Error( 'Missing webhook secret: TWILIO_AUTH_TOKEN' ), { status : 500 });
+
+				const params = new URLSearchParams( String( body || '' ) );
+
+				const signed = url + [ ...params.keys() ].sort().map( ( key ) => key + params.get( key ) ).join( '' );
+
+				const expected = createHmac( 'sha1', secret ).update( signed ).digest( 'base64' );
+				const provided = String( headers?.[ 'x-twilio-signature' ] || '' );
+
+				const matches = expected.length === provided.length
+					&& timingSafeEqual( Buffer.from( expected ), Buffer.from( provided ) );
+
+				if( ! matches ) throw Object.assign( new Error( 'Invalid Twilio signature' ), { status : 401 });
+
+				return Object.fromEntries( params );
+
+			}
+
+		},
 		lifecycle : false,
 		resources : {
 			audiences : false,
@@ -2200,6 +2316,19 @@ var drawbridge = {
 		webhook : false
 	},
 	icon: icon$3,
+
+	// WHERE TWILIO PUTS THINGS on an inbound request, and WHICH credential
+	// verifies it. `secret` names the drawbridge provider's smsToken — the route
+	// resolves the name to the stored value and hands it to verify.
+	inbound : {
+		headers : {
+			id : 'i-twilio-idempotency-token',
+			signature : 'x-twilio-signature'
+		},
+		signature : {
+			secret : 'TWILIO_AUTH_TOKEN'
+		}
+	},
 	// PRIVATE: never in the catalog, always available to the builder.
 	private : true,
 	// THE PLATFORM'S OWN SENDING CREDENTIALS — SendGrid, Twilio, and the internal
@@ -5332,7 +5461,17 @@ const build = ( manifest ) => {
 	// A vendor that receives from the outside must say where it puts the event
 	// name. Without it the receiver has nothing to dispatch on, and the failure
 	// is a request accepted and dropped rather than an error.
-	if( implemented( manifest.hooks, 'inbound.event' ) && ! manifest.inbound?.headers?.event ){
+	//
+	// A vendor may derive the event from the CHANNEL instead — Twilio sends no
+	// topic header, so drawbridge's inbound.event is a constant and the
+	// registered url is the topic. What is required is that SOMETHING names the
+	// event: a declared header, or an event hook that answers without one. The
+	// build cannot see inside the function, so the hook's existence is the
+	// declaration — and a hook that returns nothing still fails at the route,
+	// where a null event is refused before it is buffered.
+	if( implemented( manifest.hooks, 'inbound.event' )
+		&& typeof manifest.hooks?.inbound?.event !== 'function'
+		&& ! manifest.inbound?.headers?.event ){
 
 		throw new Error( manifest.slug + ' implements inbound.event but declares no inbound.headers.event' );
 

package/dist/connections/index.js

@@ -177,7 +177,7 @@ var HOOKS = Object.freeze({
   ])
 });
 var HOOK_EFFECTS = Object.freeze(["enqueues", "events", "writes"]);
-var WRITE_OPERATIONS = Object.freeze(["create", "update"]);
+var WRITE_OPERATIONS = Object.freeze(["create", "delete", "update"]);
 var HOOK_PROPS = Object.freeze([
   "channel",
   "clientId",
@@ -237,9 +237,9 @@ var effectsOf = (answer) => {
     if (!WRITE_OPERATIONS.includes(write == null ? void 0 : write.operation)) {
       throw new Error("A described write on " + write.collection + " needs an operation \u2014 one of " + WRITE_OPERATIONS.join(", "));
     }
-    if (!(write == null ? void 0 : write.data)) throw new Error("A described write on " + write.collection + " carries no data");
-    if (write.operation === "update" && !write.query) {
-      throw new Error("A described update on " + write.collection + " has no query \u2014 that is every document in it");
+    if (write.operation !== "delete" && !(write == null ? void 0 : write.data)) throw new Error("A described write on " + write.collection + " carries no data");
+    if (["delete", "update"].includes(write.operation) && !write.query) {
+      throw new Error("A described " + write.operation + " on " + write.collection + " has no query \u2014 that is every document in it");
     }
     if (write.operation === "create" && write.query) {
       throw new Error("A described create on " + write.collection + " carries a query \u2014 create does not filter");
@@ -835,6 +835,9 @@ var attentive_default2 = {
   title: "Attentive"
 };
 
+// lib/connections/providers/drawbridge.js
+import { createHmac, timingSafeEqual } from "crypto";
+
 // lib/http.js
 var DEFAULT_TIMEOUT_MS = 15e3;
 var request = async ({
@@ -1661,6 +1664,8 @@ var channels = {
 };
 
 // lib/connections/providers/drawbridge.js
+var STOP_KEYWORDS = ["STOP", "STOPALL", "UNSUBSCRIBE", "CANCEL", "END", "QUIT"];
+var START_KEYWORDS = ["START", "UNSTOP", "YES"];
 var interpolate = (template, data2) => {
   if (!template) return template;
   return template.replace(/\{\{(\w+)\}\}/g, (_, key) => (data2 == null ? void 0 : data2[key]) != null ? String(data2[key]) : "{{" + key + "}}");
@@ -1888,7 +1893,88 @@ var drawbridge_default2 = {
         };
       }
     },
-    inbound: false,
+    // INBOUND SMS to the platform number. Twilio's webhook, verified and
+    // processed HERE — the manifest owns its own inbound, the same as every
+    // other vendor, and the bespoke webhooks route + the handler that lived in
+    // sync's buffer table are gone.
+    inbound: {
+      // EVERY POST ON THIS CHANNEL IS AN INBOUND MESSAGE. Twilio sends no
+      // topic header — the registered url IS the topic.
+      event: () => "message.inbound",
+      // STOP AND START, AS DESCRIBED WRITES. A withdrawn number is withdrawn
+      // for everyone — organization : null is the platform floor canSend()
+      // reads on every send path. $setOnInsert + upsert so webhook replays
+      // and repeat STOPs collapse onto the unique { channel, address,
+      // organization } index instead of erroring.
+      process: ({ context }) => {
+        var _a, _b;
+        const keyword = String(((_a = context == null ? void 0 : context.data) == null ? void 0 : _a.Body) || "").trim().toUpperCase();
+        const address = toE164((_b = context == null ? void 0 : context.data) == null ? void 0 : _b.From);
+        if (!address) return { message: "Inbound SMS carried no usable sender number.", skipped: true };
+        if (STOP_KEYWORDS.includes(keyword)) {
+          return {
+            message: "STOP recorded \u2014 " + address + " is suppressed on SMS everywhere.",
+            request: { keyword },
+            writes: [{
+              collection: "suppression",
+              data: {
+                $setOnInsert: {
+                  address,
+                  channel: "sms",
+                  organization: null,
+                  reason: keyword,
+                  source: "stop"
+                }
+              },
+              operation: "update",
+              options: { upsert: true },
+              query: {
+                address,
+                channel: "sms",
+                organization: null
+              }
+            }]
+          };
+        }
+        if (START_KEYWORDS.includes(keyword)) {
+          return {
+            message: "START recorded \u2014 " + address + " can receive SMS again.",
+            request: { keyword },
+            writes: [{
+              collection: "suppression",
+              operation: "delete",
+              query: {
+                address,
+                channel: "sms",
+                organization: null
+              }
+            }]
+          };
+        }
+        return { message: "A real reply, not a keyword \u2014 nothing to record.", skipped: true };
+      },
+      receive: ({ payload }) => ({
+        data: payload,
+        provider: { id: (payload == null ? void 0 : payload.MessageSid) || null }
+      }),
+      // TWILIO'S SCHEME, from docs.twilio.com/usage/security: take the full
+      // registered url, sort the POST parameters alphabetically (Unix-style,
+      // case-sensitive), append each name and value with no delimiters, sign
+      // with HMAC-SHA1 keyed by the AuthToken, base64 — compared against
+      // X-Twilio-Signature. It signs the URL rather than the raw body, which
+      // is exactly why the shared body-HMAC verifier cannot cover it and this
+      // hook exists.
+      verify: ({ body, headers, secret, url }) => {
+        if (!secret) throw Object.assign(new Error("Missing webhook secret: TWILIO_AUTH_TOKEN"), { status: 500 });
+        const params = new URLSearchParams(String(body || ""));
+        const signed = url + [...params.keys()].sort().map((key) => key + params.get(key)).join("");
+        const expected = createHmac("sha1", secret).update(signed).digest("base64");
+        const provided = String((headers == null ? void 0 : headers["x-twilio-signature"]) || "");
+        const matches = expected.length === provided.length && timingSafeEqual(Buffer.from(expected), Buffer.from(provided));
+        if (!matches) throw Object.assign(new Error("Invalid Twilio signature"), { status: 401 });
+        return Object.fromEntries(params);
+      }
+    },
     lifecycle: false,
     resources: {
       audiences: false,
@@ -2067,6 +2153,18 @@ var drawbridge_default2 = {
     webhook: false
   },
   icon: drawbridge_default,
+  // WHERE TWILIO PUTS THINGS on an inbound request, and WHICH credential
+  // verifies it. `secret` names the drawbridge provider's smsToken — the route
+  // resolves the name to the stored value and hands it to verify.
+  inbound: {
+    headers: {
+      id: "i-twilio-idempotency-token",
+      signature: "x-twilio-signature"
+    },
+    signature: {
+      secret: "TWILIO_AUTH_TOKEN"
+    }
+  },
   // PRIVATE: never in the catalog, always available to the builder.
   private: true,
   // THE PLATFORM'S OWN SENDING CREDENTIALS — SendGrid, Twilio, and the internal
@@ -3029,7 +3127,7 @@ var shopify_default = `<svg width="500" height="500" viewBox="0 0 500 500" fill=
 </svg>`;
 
 // lib/connections/inbound.js
-import { createHmac, timingSafeEqual } from "crypto";
+import { createHmac as createHmac2, timingSafeEqual as timingSafeEqual2 } from "crypto";
 var verifySignature = ({ body, descriptor, headers, secret }) => {
   if (!secret) {
     throw Object.assign(new Error("Missing webhook secret: " + descriptor.signature.secret), { status: 500 });
@@ -3038,10 +3136,10 @@ var verifySignature = ({ body, descriptor, headers, secret }) => {
   if (!provided) {
     throw Object.assign(new Error("Missing webhook signature"), { status: 401 });
   }
-  const digest = createHmac(descriptor.signature.algorithm, secret).update(body).digest(descriptor.signature.encoding);
+  const digest = createHmac2(descriptor.signature.algorithm, secret).update(body).digest(descriptor.signature.encoding);
   const digestBuffer = Buffer.from(digest, descriptor.signature.encoding);
   const providedBuffer = Buffer.from(provided, descriptor.signature.encoding);
-  if (digestBuffer.length !== providedBuffer.length || !timingSafeEqual(digestBuffer, providedBuffer)) {
+  if (digestBuffer.length !== providedBuffer.length || !timingSafeEqual2(digestBuffer, providedBuffer)) {
     throw Object.assign(new Error("Invalid webhook signature"), { status: 401 });
   }
   return JSON.parse(body.toString());
@@ -4373,7 +4471,7 @@ var leaves = (node, path = []) => Object.entries(node || {}).flatMap(
   ([key, value]) => typeof value === "function" ? [[[...path, key].join("."), value]] : value && typeof value === "object" ? leaves(value, [...path, key]) : []
 );
 var build = (manifest) => {
-  var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n, _o, _p, _q, _r;
+  var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n, _o, _p, _q, _r, _s, _t;
   if (!(manifest == null ? void 0 : manifest.slug)) throw new Error("A connection needs a slug");
   if (!(manifest == null ? void 0 : manifest.title)) throw new Error(manifest.slug + " needs a title");
   if (!(manifest == null ? void 0 : manifest.private) && !(manifest == null ? void 0 : manifest.feature)) throw new Error(manifest.slug + " needs a plan feature key");
@@ -4452,16 +4550,16 @@ var build = (manifest) => {
       );
     }
   }
-  if (implemented(manifest.hooks, "inbound.event") && !((_l = (_k = manifest.inbound) == null ? void 0 : _k.headers) == null ? void 0 : _l.event)) {
+  if (implemented(manifest.hooks, "inbound.event") && typeof ((_l = (_k = manifest.hooks) == null ? void 0 : _k.inbound) == null ? void 0 : _l.event) !== "function" && !((_n = (_m = manifest.inbound) == null ? void 0 : _m.headers) == null ? void 0 : _n.event)) {
     throw new Error(manifest.slug + " implements inbound.event but declares no inbound.headers.event");
   }
-  if (implemented(manifest.hooks, "inbound.verify") && !((_n = (_m = manifest.inbound) == null ? void 0 : _m.headers) == null ? void 0 : _n.signature)) {
+  if (implemented(manifest.hooks, "inbound.verify") && !((_p = (_o = manifest.inbound) == null ? void 0 : _o.headers) == null ? void 0 : _p.signature)) {
     throw new Error(manifest.slug + " implements inbound.verify but declares no inbound.headers.signature");
   }
   if (typeof (manifest == null ? void 0 : manifest.status) !== "function") {
     throw new Error(manifest.slug + " must declare status( data ) \u2014 return null to accept the connection's own status, or { message, status } to override it");
   }
-  if (!Array.isArray((_o = manifest == null ? void 0 : manifest.content) == null ? void 0 : _o.guide) || !manifest.content.guide.length) {
+  if (!Array.isArray((_q = manifest == null ? void 0 : manifest.content) == null ? void 0 : _q.guide) || !manifest.content.guide.length) {
     throw new Error(manifest.slug + " needs content.guide \u2014 an array of steps for its page");
   }
   if (typeof (manifest == null ? void 0 : manifest.status) !== "function") {
@@ -4473,8 +4571,8 @@ var build = (manifest) => {
   }
   for (const [domain, verbs] of Object.entries(HOOKS)) {
     for (const verb of verbs) {
-      const hook = (_q = (_p = manifest.hooks) == null ? void 0 : _p[domain]) == null ? void 0 : _q[verb];
-      if (((_r = manifest.hooks) == null ? void 0 : _r[domain]) === false) continue;
+      const hook = (_s = (_r = manifest.hooks) == null ? void 0 : _r[domain]) == null ? void 0 : _s[verb];
+      if (((_t = manifest.hooks) == null ? void 0 : _t[domain]) === false) continue;
       if (hook !== false && !implemented({ [domain]: { [verb]: hook } }, domain + "." + verb)) {
         throw new Error(manifest.slug + " must answer hooks." + domain + "." + verb + " \u2014 false, a function, or {} if another repo implements it");
       }