@drawbridge/drawbridge-utils 0.0.156 → 0.0.158

package/dist/connections/index.d.cts

@@ -1,7 +1,7 @@
 import { authToken } from './oauth.cjs';
 export { consentUrl, pkcePair } from './oauth.cjs';
 import { toE164, detectCountry } from '../phone.cjs';
-import crypto, { createHmac, timingSafeEqual, createHash, randomUUID } from 'node:crypto';
+import crypto, { createHmac, timingSafeEqual, createVerify, createHash, randomUUID } from 'node:crypto';
 import { request } from '../http.cjs';
 import { channels } from '../pricing.cjs';
 import { customAlphabet } from 'nanoid';
@@ -1273,6 +1273,144 @@ var attentive = {
 	title : 'Attentive'
 };
 
+// THE SHARED HALF OF inbound.verify.
+//
+// A vendor whose scheme is "hash the raw body with a shared secret and compare,
+// constant-time, against a header" declares that shape as `inbound.signature`
+// data on its manifest (algorithm, encoding, the NAME of the credential) and
+// wires this straight in as its hook — Shopify does exactly that.
+//
+// A vendor whose scheme is not that shape — Twilio signs the REGISTERED URL
+// rather than the body, a JWT-bodied vendor verifies against a JWKS — writes its
+// own inbound.verify instead. That is why verify is a hook and not config: this
+// file covers the common case, not the contract.
+const verifySignature = ({ body, descriptor, headers, secret }) => {
+
+	// THE MANIFEST STILL DECLARES THE NAME, the caller supplies the value.
+	// descriptor.signature.secret is 'SHOPIFY_API_SECRET' and stays that way —
+	// naming which credential a vendor needs is the manifest's job. Reading it is
+	// not: the value lives encrypted in the `provider` collection, and a package
+	// that reached into process.env for it would force every service to copy the
+	// collection back into its environment at boot before this could work.
+	//
+	// A 500 rather than the 401 below, because a secret we never loaded is our
+	// misconfiguration and must not be indistinguishable in the logs from the
+	// forged request that gets the same door slammed on it.
+	if( ! secret ){
+
+		throw Object.assign( new Error( 'Missing webhook secret: ' + descriptor.signature.secret ), { status : 500 });
+
+	}
+
+	const provided = headers[ descriptor.headers.signature ];
+
+	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 );
+
+	// Buffers of different lengths crash timingSafeEqual rather than compare
+	// false — decided here, before the length itself becomes a timing signal.
+	const digestBuffer = Buffer.from( digest, descriptor.signature.encoding );
+	const providedBuffer = Buffer.from( provided, descriptor.signature.encoding );
+
+	if(
+		digestBuffer.length !== providedBuffer.length ||
+		! timingSafeEqual( digestBuffer, providedBuffer )
+	){
+
+		throw Object.assign( new Error( 'Invalid webhook signature' ), { status : 401 });
+
+	}
+
+	// The proof and the parse happen together on purpose. Nothing downstream of
+	// inbound.verify ever sees the raw bytes, which is what makes acting on
+	// unverified data impossible rather than merely discouraged.
+	return JSON.parse( body.toString() );
+
+};
+
+// How far out of date a signed payload may be. SendGrid hands us a timestamp
+// precisely so a captured delivery cannot be replayed forever, so we spend it.
+// Shopify gets no equivalent check because Shopify sends no timestamp — the
+// difference is what each vendor offers, not a different standard.
+const REPLAY_TOLERANCE_SECONDS = 5 * 60;
+
+// Wrap SendGrid's base64 DER (SPKI) verification key as PEM, which is the only
+// form node's verifier takes. The console shows it as one unbroken base64 line;
+// PEM wants it in 64-character rows.
+const asPem = ( key ) => [
+	'-----BEGIN PUBLIC KEY-----',
+	...( key.match( /.{1,64}/g ) || [] ),
+	'-----END PUBLIC KEY-----'
+].join( '\n' );
+
+// THE OTHER SHARED SCHEME: ECDSA over timestamp + raw body, against a PUBLIC
+// key rather than a shared secret. SendGrid signs this way, and the asymmetry
+// matters — `secret` here is the vendor's public verification key, so it proves
+// the sender without ever being able to impersonate them.
+//
+// The raw bytes are load-bearing. SendGrid's own documentation is explicit that
+// the payload must be verified "in its raw bytes form" because a JSON round-trip
+// can drop characters that were signed. That is why the route hands verify a
+// Buffer and parses only after the proof, exactly as the HMAC path does.
+const verifyEcdsa = ({ body, descriptor, headers, secret }) => {
+
+	// Same reasoning as verifySignature: a key we never loaded is our
+	// misconfiguration, and a 500 keeps it out of the forged-request logs.
+	if( ! secret ){
+
+		throw Object.assign( new Error( 'Missing webhook key: ' + descriptor.signature.secret ), { status : 500 });
+
+	}
+
+	const provided = headers[ descriptor.headers.signature ];
+	const timestamp = headers[ descriptor.headers.timestamp ];
+
+	if( ! provided || ! timestamp ){
+
+		throw Object.assign( new Error( 'Missing webhook signature' ), { status : 401 });
+
+	}
+
+	const age = Math.abs( Math.floor( Date.now() / 1000 ) - Number( timestamp ) );
+
+	// NaN fails this too, which is the point — an unparseable timestamp is not a
+	// fresh one.
+	if( ! ( age <= REPLAY_TOLERANCE_SECONDS ) ){
+
+		throw Object.assign( new Error( 'Stale webhook signature' ), { status : 401 });
+
+	}
+
+	// CONCATENATED AS BYTES, not as strings. `timestamp + body.toString()` would
+	// decode the body as utf8 first, and any byte sequence that is not valid utf8
+	// comes back as a replacement character — signed bytes silently replaced by
+	// different bytes, and a valid delivery fails verification.
+	const payload = Buffer.concat([ Buffer.from( String( timestamp ), 'utf8' ), body ]);
+
+	const verified = createVerify( 'sha256' )
+		.update( payload )
+		.verify( asPem( secret ), Buffer.from( provided, 'base64' ) );
+
+	if( ! verified ){
+
+		throw Object.assign( new Error( 'Invalid webhook signature' ), { status : 401 });
+
+	}
+
+	return JSON.parse( body.toString() );
+
+};
+
+// THE SHARED HALF OF inbound.event, for a vendor that puts it in a header.
+const readEventHeader = ({ descriptor, headers }) => headers[ descriptor.headers.event ];
+
 // DRAWBRIDGE'S OWN HUBSPOT PORTAL, kept in step with account signups so the
 // campaign a customer arrived on is on their contact record.
 //
@@ -1668,6 +1806,230 @@ var twilioIcon = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none
 const STOP_KEYWORDS = [ 'STOP', 'STOPALL', 'UNSUBSCRIBE', 'CANCEL', 'END', 'QUIT' ];
 const START_KEYWORDS = [ 'START', 'UNSTOP', 'YES' ];
 
+// WHERE SENDGRID PUTS THINGS on an event delivery. Its own descriptor because
+// the scheme has nothing in common with Twilio's: ECDSA over timestamp + raw
+// body against a public key, versus HMAC over the registered url.
+const sendgridInbound = {
+	headers : {
+		signature : 'x-twilio-email-event-webhook-signature',
+		timestamp : 'x-twilio-email-event-webhook-timestamp'
+	},
+	signature : {
+		secret : 'SENDGRID_EVENT_WEBHOOK_KEY'
+	}
+};
+
+// The events that mean a message did not arrive. Only these carry a reason worth
+// reading — a delivered event's `response` is a 250 nobody needs.
+const REFUSALS = new Set([ 'blocked', 'bounce', 'deferred', 'dropped', 'spamreport' ]);
+
+// ONE VOCABULARY FOR EVERY CHANNEL, and the rank is what makes it safe to write.
+//
+// Delivery events are not ordered. SendGrid can deliver a `deferred` after a
+// `delivered`, retries duplicate, and an asynchronous bounce can arrive days
+// later. A plain $set of the newest event lets a stale one overwrite a final
+// one, so the rank rides IN the document and the write guards on it — the
+// comparison happens in the query, atomically, instead of in a read-then-write
+// that two workers can interleave.
+//
+// TERMINAL-BAD OUTRANKS DELIVERED on purpose. A bounce or a spam complaint
+// arriving after delivery is the more informative fact and exactly the
+// transition worth seeing; nothing else may move the status backwards.
+const DELIVERY = {
+	queued : 10,
+	sent : 20,
+	deferred : 30,
+	blocked : 40,
+	delivered : 50,
+	bounced : 60,
+	complained : 70
+};
+
+// SendGrid's event names, and the one case where the event name is not enough:
+// a `bounce` is permanent or temporary depending on `type`, same event either
+// way. Getting that wrong means treating a full mailbox like a dead address.
+const fromSendgrid = ( event ) => {
+
+	if( event?.event === 'bounce' ) return event.type === 'blocked' ? 'blocked' : 'bounced';
+
+	return ({
+		blocked : 'blocked',
+		deferred : 'deferred',
+		delivered : 'delivered',
+		dropped : 'bounced',
+		processed : 'queued',
+		spamreport : 'complained'
+	})[ event?.event ] || null;
+
+};
+
+// Twilio's MessageStatus. `failed` never left Twilio, `undelivered` left and the
+// carrier refused it — both are dead ends for this address, so both land on
+// bounced rather than inventing a status nothing else can produce.
+const fromTwilio = ( status ) => ({
+	delivered : 'delivered',
+	failed : 'bounced',
+	queued : 'queued',
+	sending : 'sent',
+	sent : 'sent',
+	undelivered : 'bounced'
+})[ String( status || '' ).toLowerCase() ] || null;
+
+// THE WRITE ITSELF, identical for both channels because only `status` had to be
+// normalised. `code` and `reason` stay the vendor's own words — 5.0.0 and "500
+// unknown recipient" from SendGrid, 30003 and "Unreachable destination handset"
+// from Twilio — normalised in position, never in content.
+//
+// Adding a third vendor adds a mapper and a slug. It changes neither this
+// function, nor the shape, nor anything that reads it.
+const deliveryWrite = ({ at, code, notification, permanent, provider, reason, status }) => {
+
+	const rank = DELIVERY[ status ];
+
+	if( ! notification || ! rank ) return null;
+
+	return {
+		collection : 'notification',
+		data : {
+			$set : {
+				'meta.delivery' : {
+					at : at || new Date(),
+					...( code !== undefined && code !== null && { code : String( code ) }),
+					...( permanent !== undefined && { permanent }),
+					provider,
+					rank,
+					...( reason && { reason : String( reason ) }),
+					status
+				}
+			}
+		},
+		operation : 'update',
+		query : {
+			id : notification,
+			// NEVER an upsert. A callback naming a notification we do not have is a
+			// vendor talking about someone else's message, not a document to create.
+			$or : [
+				{ 'meta.delivery.rank' : { $exists : false } },
+				{ 'meta.delivery.rank' : { $lt : rank } }
+			]
+		}
+	};
+
+};
+
+// SendGrid batches events, so this summarises the lot into one log line AND
+// describes a write per event that names a notification. The log line is what
+// makes a deliverability question answerable at a glance; the writes are what
+// make it answerable in the admin three weeks later.
+//
+// It still writes no suppression. Turning a bounce or a spam report into a
+// consent decision is a product call, not a side effect to smuggle in with the
+// plumbing.
+//
+// `custom_args` are absent on an asynchronous bounce (SendGrid documents this),
+// so some real bounces name no notification and can only be counted, never
+// attributed. That is why an empty meta.delivery must never render as delivered.
+const summariseEvents = ( events ) => {
+
+	const list = Array.isArray( events ) ? events : [];
+
+	if( ! list.length ) return { message : 'SendGrid delivered an empty event batch.', skipped : true };
+
+	const counts = {};
+
+	for( const { event } of list ){
+
+		const name = event || 'unknown';
+
+		counts[ name ] = ( counts[ name ] || 0 ) + 1;
+
+	}
+
+	const tally = Object.entries( counts ).map( ( [ name, count ] ) => count + ' ' + name ).join( ', ' );
+
+	// Capped: a batch can carry hundreds, and a log line that carries all of them
+	// is one nobody reads.
+	const refused = list
+		.filter( ( { event } ) => REFUSALS.has( event ) )
+		.slice( 0, 5 )
+		.map( ( { email, reason, response, status } ) => email + ' — ' + ( reason || response || status || 'no reason given' ) );
+
+	const writes = list
+		.map( ( event ) => deliveryWrite({
+			at : event.timestamp ? new Date( event.timestamp * 1000 ) : undefined,
+			code : event.status,
+			// Read BOTH shapes. SendGrid echoes custom_args as siblings of `email`
+			// and `event`, which is why it warns about colliding with reserved
+			// names — but this is the one thing in the design that cannot be proved
+			// until a real event arrives, and reading the nested form too costs a
+			// token and removes the only silent failure left here.
+			notification : event.notification || event.custom_args?.notification,
+			// Only a bounce carries the distinction, and only a real one is
+			// permanent — `blocked` is this attempt refused, not this address dead.
+			...( event.event === 'bounce' && { permanent : event.type !== 'blocked' }),
+			provider : { slug : 'sendgrid', id : event.sg_message_id || null },
+			reason : event.reason || event.response,
+			status : fromSendgrid( event )
+		}) )
+		.filter( Boolean );
+
+	return {
+		message : [ list.length + ' SendGrid event(s): ' + tally, ...refused ].join( ' | ' ),
+		...( writes.length ? { writes } : { skipped : true })
+	};
+
+};
+
+// Twilio posts ONE status per callback, form-encoded, where SendGrid posts a JSON
+// array. Normalising here is what lets both channels land in the same field.
+//
+// The notification is found by MessageSid rather than by an echoed id: Twilio's
+// create call returns the sid synchronously, so the send stamps it and the
+// callback joins on it. No query-string trick, and nothing depending on whether
+// Twilio preserves custom params through its signature.
+const statusCallback = ( data ) => {
+
+	const status = fromTwilio( data?.MessageStatus || data?.SmsStatus );
+
+	if( ! status ) return { message : 'Twilio sent a status this does not map: ' + ( data?.MessageStatus || 'none' ), skipped : true };
+
+	const rank = DELIVERY[ status ];
+
+	const write = {
+		collection : 'notification',
+		data : {
+			$set : {
+				'meta.delivery' : {
+					at : new Date(),
+					...( data?.ErrorCode && { code : String( data.ErrorCode ) }),
+					// `failed` never left Twilio and `undelivered` was refused by the
+					// carrier. Both are dead ends for this handset, so neither is
+					// reported as a temporary condition.
+					...( status === 'bounced' && { permanent : true }),
+					provider : { slug : 'twilio', id : data?.MessageSid || null },
+					rank,
+					...( data?.ErrorMessage && { reason : String( data.ErrorMessage ) }),
+					status
+				}
+			}
+		},
+		operation : 'update',
+		query : {
+			'meta.delivery.provider.id' : data?.MessageSid,
+			$or : [
+				{ 'meta.delivery.rank' : { $exists : false } },
+				{ 'meta.delivery.rank' : { $lt : rank } }
+			]
+		}
+	};
+
+	return {
+		message : 'Twilio ' + status + ' for ' + ( data?.MessageSid || 'an unnamed message' ) + ( data?.ErrorCode ? ' (' + data.ErrorCode + ')' : '' ),
+		...( data?.MessageSid ? { writes : [ write ] } : { skipped : true })
+	};
+
+};
+
 // Drawbridge itself — the PRIVATE connection.
 //
 // Nobody connects this. There is no credential, no consent, and no card on the
@@ -2075,9 +2437,16 @@ var drawbridge = {
 		// 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',
+			// THE REGISTERED URL IS THE TOPIC. Neither vendor sends a topic header,
+			// so the channel it arrived on names the event — `sms` is one inbound
+			// message, `email` is a batch of SendGrid delivery events.
+			//
+			// Defaulted because the drain calls `event()` with nothing when it only
+			// wants the SMS name.
+			event : ({ channel } = {}) => ({
+				email : 'email.events',
+				'sms-status' : 'sms.status'
+			})[ channel ] || 'message.inbound',
 
 			// STOP AND START, AS DESCRIBED WRITES. A withdrawn number is withdrawn
 			// for everyone — organization : null is the platform floor canSend()
@@ -2086,6 +2455,17 @@ var drawbridge = {
 			// organization } index instead of erroring.
 			process : ({ context }) => {
 
+				// BRANCHES ON TOPIC, NOT CHANNEL. The drain reads a buffer row, which
+				// carries the type this manifest named at receive time and no memory
+				// of the url it arrived on — `channel` simply is not in scope here.
+				//
+				// Not optional: the drain hands EVERY drawbridge buffer row to this
+				// hook, so without the branch a SendGrid batch falls into the Twilio
+				// path below, finds no `Body`, and logs itself as an inbound SMS that
+				// carried no usable sender number.
+				if( context?.topic === 'email.events' ) return summariseEvents( context?.data );
+				if( context?.topic === 'sms.status' ) return statusCallback( context?.data );
+
 				const keyword = String( context?.data?.Body || '' ).trim().toUpperCase();
 				const address = toE164( context?.data?.From );
 
@@ -2141,9 +2521,14 @@ var drawbridge = {
 
 			},
 
-			receive : ({ payload }) => ({
+			// A SendGrid batch carries many sg_message_ids and no single identity, so
+			// it names no provider id. That means no dedupe key for a redelivery —
+			// acceptable because SendGrid only retries a non-2xx, and the cost of a
+			// duplicate here is a second buffer row rather than a repeated side
+			// effect. Revisit if this ever writes suppressions.
+			receive : ({ channel, payload }) => ({
 				data : payload,
-				provider : { id : payload?.MessageSid || null }
+				provider : { id : channel === 'email' ? null : payload?.MessageSid || null }
 			}),
 
 			// TWILIO'S SCHEME, from docs.twilio.com/usage/security: take the full
@@ -2153,7 +2538,12 @@ var drawbridge = {
 			// 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 }) => {
+			verify : ({ body, channel, headers, secret, url }) => {
+
+				// SendGrid signs timestamp + raw body with ECDSA, against a public
+				// key. Nothing in Twilio's scheme below applies, which is why the
+				// channel decides here rather than the manifest declaring one shape.
+				if( channel === 'email' ) return verifyEcdsa({ body, descriptor : sendgridInbound, headers, secret });
 
 				// OUR misconfiguration, never a forgery — a missing credential must
 				// not be answered 401.
@@ -2446,15 +2836,30 @@ var drawbridge = {
 	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.
+	// verifies each channel. The route resolves the NAME to the stored value and
+	// hands it to verify; this manifest never reads a store.
+	//
+	// `signature.channels` because this is the one manifest that receives from two
+	// different vendors — Twilio on `sms`, SendGrid on `email` — which need
+	// different credentials and share no scheme. A manifest whose channels all
+	// verify the same way keeps declaring `signature` flat, and the route falls
+	// back to it; Shopify's two channels do exactly that.
 	inbound : {
 		headers : {
 			id : 'i-twilio-idempotency-token',
 			signature : 'x-twilio-signature'
 		},
 		signature : {
-			secret : 'TWILIO_AUTH_TOKEN'
+			channels : {
+				email : sendgridInbound.signature,
+				sms : { secret : 'TWILIO_AUTH_TOKEN' },
+				// Outbound delivery receipts, which Twilio signs exactly as it signs
+				// an inbound message — same scheme, same credential, different url.
+				// Separate channel because the payload is a MessageStatus rather than
+				// a message, and conflating them would put a STOP keyword check on a
+				// delivery receipt.
+				'sms-status' : { secret : 'TWILIO_AUTH_TOKEN' }
+			}
 		}
 	},
 	// PRIVATE: never in the catalog, always available to the builder.
@@ -2486,6 +2891,13 @@ var drawbridge = {
 					// Optional: SENDGRID_SEND_FROM_ADDRESS is not boot-required in sync
 					// either. Unset, it degrades to the account sender rather than
 					// refusing to start.
+					// NOT redacted, because it is a PUBLIC key. Marking it secret would
+					// be theatre, and it would stop an operator reading back the value
+					// they need to compare against the SendGrid console.
+					//
+					// Optional: absent, the event webhook answers 500 on verify rather
+					// than accepting unverified deliveries, and nothing else notices.
+					{ input : 'text', key : 'eventKey', credential : 'SENDGRID_EVENT_WEBHOOK_KEY', label : 'Event webhook key', message : 'SendGrid, Settings, Mail Settings, Event Webhook — the verification key shown once signature verification is enabled. Public, not a secret.' },
 					{ input : 'email', key : 'leadSender', credential : 'SENDGRID_SEND_FROM_ADDRESS', label : 'Lead sender', message : 'The default for lead-facing mail when a merchant has not verified their own domain.' }
 				],
 				icon : sendgridIcon,
@@ -3956,71 +4368,6 @@ var icon = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xmln
 <path d="M300.325 382.771L368 365.96C368 365.96 338.904 169.185 338.689 167.892C338.473 166.599 337.396 165.737 336.318 165.737C335.24 165.737 316.274 165.306 316.274 165.306C316.274 165.306 304.636 154.099 300.325 149.788V382.771Z" fill="white"/>
 </svg>`;
 
-// THE SHARED HALF OF inbound.verify.
-//
-// A vendor whose scheme is "hash the raw body with a shared secret and compare,
-// constant-time, against a header" declares that shape as `inbound.signature`
-// data on its manifest (algorithm, encoding, the NAME of the credential) and
-// wires this straight in as its hook — Shopify does exactly that.
-//
-// A vendor whose scheme is not that shape — Twilio signs the REGISTERED URL
-// rather than the body, a JWT-bodied vendor verifies against a JWKS — writes its
-// own inbound.verify instead. That is why verify is a hook and not config: this
-// file covers the common case, not the contract.
-const verifySignature = ({ body, descriptor, headers, secret }) => {
-
-	// THE MANIFEST STILL DECLARES THE NAME, the caller supplies the value.
-	// descriptor.signature.secret is 'SHOPIFY_API_SECRET' and stays that way —
-	// naming which credential a vendor needs is the manifest's job. Reading it is
-	// not: the value lives encrypted in the `provider` collection, and a package
-	// that reached into process.env for it would force every service to copy the
-	// collection back into its environment at boot before this could work.
-	//
-	// A 500 rather than the 401 below, because a secret we never loaded is our
-	// misconfiguration and must not be indistinguishable in the logs from the
-	// forged request that gets the same door slammed on it.
-	if( ! secret ){
-
-		throw Object.assign( new Error( 'Missing webhook secret: ' + descriptor.signature.secret ), { status : 500 });
-
-	}
-
-	const provided = headers[ descriptor.headers.signature ];
-
-	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 );
-
-	// Buffers of different lengths crash timingSafeEqual rather than compare
-	// false — decided here, before the length itself becomes a timing signal.
-	const digestBuffer = Buffer.from( digest, descriptor.signature.encoding );
-	const providedBuffer = Buffer.from( provided, descriptor.signature.encoding );
-
-	if(
-		digestBuffer.length !== providedBuffer.length ||
-		! timingSafeEqual( digestBuffer, providedBuffer )
-	){
-
-		throw Object.assign( new Error( 'Invalid webhook signature' ), { status : 401 });
-
-	}
-
-	// The proof and the parse happen together on purpose. Nothing downstream of
-	// inbound.verify ever sees the raw bytes, which is what makes acting on
-	// unverified data impossible rather than merely discouraged.
-	return JSON.parse( body.toString() );
-
-};
-
-// THE SHARED HALF OF inbound.event, for a vendor that puts it in a header.
-const readEventHeader = ({ descriptor, headers }) => headers[ descriptor.headers.event ];
-
 // ── ORDER ATTRIBUTION, the vendor's own arithmetic ───────────────────────────
 //
 // Orders are attributed via `_drwbrdg_*` line-item properties injected at
@@ -5872,6 +6219,39 @@ var shopify = {
 // Webhooks — the only connection with no third party behind it. Connecting
 // generates a signing secret rather than asking for a credential, which is why
 // its one field declares no `input`.
+
+// A receiver owes us a status, not a document. Whatever it returns is buffered
+// whole in the worker and written to the run record, so it is bounded.
+const RESPONSE_LIMIT = 64 * 1024;
+
+// STRIPE-SHAPED: `t=<unix seconds>,v1=<hex>[,v1=<hex>]`, over `<t>.<raw body>`.
+// The timestamp is INSIDE the signed string, so a captured delivery stops
+// verifying once the receiver's tolerance passes — signing the body alone made a
+// replay valid forever. A second v1 carries the previous secret while a
+// regeneration's grace window is open (the api stamps `previous.until`), so a
+// receiver still on the old value keeps verifying mid-rotation instead of
+// failing every delivery between the button press and their config change.
+const signature = ( { body, settings } ) => {
+
+	const timestamp = Math.floor( Date.now() / 1000 );
+
+	const payload = timestamp + '.' + JSON.stringify( body );
+
+	const previous = settings.previous?.secret && new Date( settings.previous.until ) > new Date()
+		? [ settings.previous.secret ]
+		: [];
+
+	return [
+		't=' + timestamp,
+		...[ settings.secret, ...previous ].map( ( secret ) => 'v1=' + crypto
+			.createHmac( 'sha256', secret )
+			.update( payload )
+			.digest( 'hex' )
+		)
+	].join( ',' );
+
+};
+
 var webhook = {
 	// Connecting GENERATES the secret rather than storing one the merchant typed,
 	// so the buttons say what actually happens.
@@ -5902,7 +6282,9 @@ var webhook = {
 			'Press Connect. Drawbridge generates a signing secret and shows it here.',
 			'Copy the secret into your own endpoint.',
 			'Add a Send webhook step to a workflow and put your endpoint URL on it. The URL belongs to the step rather than the connection, so one connection can serve several endpoints.',
-			'On each request, compute HMAC-SHA256 of the raw body using the secret and compare it against the X-Drawbridge-Signature header before acting on the payload.'
+			'On each request, read the X-Drawbridge-Signature header — `t=<unix seconds>,v1=<hex>` — and compute HMAC-SHA256 of `<t>.<raw request body>` with the secret. Use the raw bytes, not a re-serialised parse.',
+			'Compare your result against each v1 value with a constant-time comparison, and reject any request whose timestamp is more than five minutes old.',
+			'After you regenerate the secret, the previous one keeps signing for 24 hours (as a second v1), so update your endpoint within that window.'
 		]
 	},
 	// Nothing to be exclusive with — there is no second webhook vendor, and a
@@ -5975,6 +6357,11 @@ var webhook = {
 
 			if( ! url ) return { message : 'Outgoing webhook URL is not configured for this step.', request, response : { skipped : true }, skipped : true };
 
+			// HTTPS ONLY. The body is the lead — email, phone, address — and a
+			// signature authenticates it without hiding it. The api refuses one on
+			// save; this catches a document written any other way.
+			if( ! /^https:\/\//i.test( url ) ) return { message : 'Outgoing webhook URL must use https.', request, response : { skipped : true }, skipped : true };
+
 			// The LEAD, when there is one, rather than the accumulated context. A
 			// receiver wants the entrant's record, not our internal step state —
 			// and the shell already resolved it, because every hook that names a
@@ -5990,14 +6377,11 @@ var webhook = {
 			// tells the merchant to check it.
 			if( settings?.secret ){
 
-			outgoing[ 'X-Drawbridge-Signature' ] = 'sha256=' + crypto
-			.createHmac( 'sha256', settings.secret )
-			.update( JSON.stringify( body ) )
-			.digest( 'hex' );
+			outgoing[ 'X-Drawbridge-Signature' ] = signature({ body, settings });
 
 			}
 
-			const response = await send({ body, headers : outgoing, method, url });
+			const response = await send({ body, headers : outgoing, maxContentLength : RESPONSE_LIMIT, method, url });
 
 			return { message : 'Webhook POSTed to ' + url + '.', request, response : response || { delivered : true } };
 
@@ -6052,7 +6436,7 @@ var webhook = {
 		: settings?.secret
 		? [
 			{
-				message : 'Compute HMAC-SHA256( secret, body ) and compare against the X-Drawbridge-Signature header to confirm each payload.',
+				message : 'Compute HMAC-SHA256( secret, t + "." + raw body ) and constant-time compare it against a v1 in the X-Drawbridge-Signature header; reject timestamps older than five minutes.',
 				title : 'Requests must be verified',
 				type : 'warning'
 			}