@drawbridge/drawbridge-utils 0.0.118 → 0.0.124

package/dist/providers.d.ts

@@ -1,7 +1,9 @@
-import { mergeSettings } from './connections/index.js';
+import { connections, mergeSettings } from './connections/index.js';
 import { decrypt, encrypt } from './encrypt.js';
 import './connections/oauth.js';
 import 'node:crypto';
+import './phone.js';
+import 'libphonenumber-js';
 import './http.js';
 import './pricing.js';
 import './plans.js';
@@ -15,6 +17,7 @@ import './usage.js';
 import './billing.js';
 import './transactions.js';
 import '@drawbridge/drawbridge-telemetry';
+import './email.js';
 import './safe-http.js';
 import 'dns';
 import 'node:http';
@@ -39,60 +42,41 @@ import './token.js';
 // the others have already rotated away.
 
 
-// WHAT AN ADMIN TYPES IN, per vendor.
+// WHAT AN ADMIN TYPES IN, per vendor — READ FROM THE MANIFESTS.
 //
-// `redact` marks a secret: never returned by the api, and blank on save means
-// keep the stored value. `required` drives the live check. `input` picks the
-// form control.
+// This was a table here, duplicating what every vendor file already knew. A
+// vendor's credentials and its `requires` name the same things, and keeping
+// them in two files meant a manifest could require a name that no admin screen
+// offered to fill — the exact shape of "declared in one place, entered in
+// another" these manifests exist to close.
 //
-// These move onto the manifests themselves as `provider : { fields }` in the
-// follow-up plan, at which point providerFields() delegates to the manifest and
-// this constant goes. It is one table for now because a vendor's credentials and
-// its manifest are declared in the same package either way.
-const FIELDS = {
-	attentive : [
-		{ input : 'text', key : 'clientId', env : 'ATTENTIVE_OAUTH_CLIENT_ID', label : 'Client ID', required : true },
-		{ input : 'password', key : 'clientSecret', env : 'ATTENTIVE_OAUTH_CLIENT_SECRET', label : 'Client secret', redact : true, required : true }
-	],
-	drawbridge : [
-		{ input : 'email', key : 'accountSender', env : 'SENDGRID_FROM_ADDRESS', label : 'Account sender', message : 'Verification codes and security alerts send from here.', required : true },
-		{ input : 'password', key : 'apiKey', env : 'SENDGRID_API_KEY', label : 'SendGrid API key', redact : true, required : true },
-		// NOT required. The CRM sync is best-effort internal tooling and no-ops
-		// without a token — requiring it would make the whole drawbridge provider
-		// read not-live over something no merchant ever sees.
-		{ input : 'password', key : 'hubspotToken', env : 'HUBSPOT_ACCESS_TOKEN', label : 'HubSpot access token', message : 'Drawbridge\'s own CRM portal. Internal — no merchant sees this.', redact : true },
-		// Optional: SENDGRID_SEND_FROM_ADDRESS is not boot-required in sync
-		// either. Unset, it degrades to the account sender rather than
-		// refusing to start.
-		{ input : 'email', key : 'leadSender', env : 'SENDGRID_SEND_FROM_ADDRESS', label : 'Lead sender', message : 'The default for lead-facing mail when a merchant has not verified their own domain.' },
-		{ input : 'text', key : 'smsFrom', env : 'TWILIO_ACCOUNT_FROM', label : 'SMS number', required : true },
-		{ input : 'password', key : 'smsSid', env : 'TWILIO_ACCOUNT_SID', label : 'Twilio account SID', redact : true, required : true },
-		{ input : 'password', key : 'smsToken', env : 'TWILIO_AUTH_TOKEN', label : 'Twilio auth token', redact : true, required : true }
-	],
-	klaviyo : [
-		{ input : 'text', key : 'clientId', env : 'KLAVIYO_OAUTH_CLIENT_ID', label : 'Client ID', required : true },
-		{ input : 'password', key : 'clientSecret', env : 'KLAVIYO_OAUTH_CLIENT_SECRET', label : 'Client secret', redact : true, required : true }
-	],
-	mailchimp : [
-		{ input : 'text', key : 'clientId', env : 'MAILCHIMP_OAUTH_CLIENT_ID', label : 'Client ID', required : true },
-		{ input : 'password', key : 'clientSecret', env : 'MAILCHIMP_OAUTH_CLIENT_SECRET', label : 'Client secret', redact : true, required : true }
-	],
-	shopify : [
-		{ input : 'text', key : 'apiKey', env : 'SHOPIFY_API_KEY', label : 'API key', required : true },
-		{ input : 'password', key : 'apiSecret', env : 'SHOPIFY_API_SECRET', label : 'API secret', redact : true, required : true },
-		{ input : 'text', key : 'appHandle', env : 'SHOPIFY_APP_HANDLE', label : 'App handle', required : true },
-		{ input : 'text', key : 'listingUrl', env : 'SHOPIFY_APP_LISTING_URL', label : 'App listing URL', required : true }
-	]
-};
-
-// Object.hasOwn, not `FIELDS[ slug ] ||` — a bare property read walks the
-// prototype chain, and FIELDS[ 'constructor' ] is a function whose .length is
-// 1, so the route's "does this vendor exist" guard passed for it and reached
+// Each field's `credential` is the NAME the rest of the system asks for that
+// value by. It is not an environment variable and there is no fallback to one:
+// the names simply began life as env vars and were kept as the vocabulary, so
+// `requires` and auth.oauth.client did not have to change when the storage
+// moved into the database.
+//
+// So the declaration lives on the manifest as `provider : { fields }`, build()
+// checks its shape at import, and this module is now only the reading, memoizing
+// and encrypting around it.
+//
+// Object.hasOwn, not `connections[ slug ] ||` — a bare property read walks the
+// prototype chain, and connections[ 'constructor' ] is a function whose .length
+// is 1, so the route's "does this vendor exist" guard passed for it and reached
 // the database before throwing.
-const providerFields = ( slug ) => Object.hasOwn( FIELDS, slug ) ? FIELDS[ slug ] : [];
+const providerFields = ( slug ) => (
+	Object.hasOwn( connections, slug ) ? ( connections[ slug ].provider?.fields || [] ) : []
+);
 
 // The vendors an admin can configure, in a stable order.
-const providerSlugs = () => Object.keys( FIELDS ).sort();
+//
+// DERIVED FROM WHO DECLARES A PROVIDER BLOCK, not from the catalog: `webhook` is
+// a connection with no vendor behind it — nothing to authenticate against and
+// nothing to type — so it must not appear on a screen whose whole purpose is
+// entering credentials.
+const providerSlugs = () => Object.keys( connections )
+	.filter( ( slug ) => connections[ slug ].provider )
+	.sort();
 
 // LIVE IS DERIVED, never stored. A stored flag is a second thing to keep in
 // sync and goes stale the moment a row is edited by hand.
@@ -120,42 +104,68 @@ const isLive = ( slug, settings ) => {
 // Fixed-width dots rather than one per character, so the length does not travel
 // either. Below the threshold a secret is short enough that a prefix and suffix
 // would be most of it, so nothing is revealed.
+//
+// SIXTEEN, not twelve. The reveal is 3 + 4 = 7 characters, so a twelve-character
+// value handed back more than half of itself while passing a check whose whole
+// point was that it did not — the threshold has to be comfortably more than
+// twice what is shown for the reasoning above to hold.
 const mask = ( value ) => {
 
 	if( ! value ) return null;
 
-	if( String( value ).length < 12 ) return '••••••••';
+	if( String( value ).length < 16 ) return '••••••••';
 
 	return String( value ).slice( 0, 3 ) + '••••••••' + String( value ).slice( -4 );
 
 };
 
-// THE CACHE KEY, in one place. All three services share one Redis, so a bust
-// from the api only clears sync's and webhooks' view if every app derives the
-// same key. Three independent derivations is one that eventually disagrees, and
-// that failure serves a credential that was already rotated away.
-const cacheKey = ( slug ) => [ 'provider', slug ];
-
-// Read a vendor's credentials. Cached, because this is on the path of every
+// A MEMO, NOT A CACHE, and the difference is the whole point. Shared Redis made
+// one process's view of a credential another process's problem: a bust from the
+// api had to reach sync and webhooks before either served a key someone had just
+// rotated because it leaked, and cache.use has no compare-and-set to make that
+// safe. Per-process state cannot be stale for anyone but the process holding it,
+// and it expires on its own.
+//
+// slug -> { at, value }, where value is the DECRYPTED settings. Exported only so
+// tests can age an entry without sleeping; nothing else should read it.
+const providerMemo = new Map();
+
+// SIXTY SECONDS, chosen for the human rather than for the load. The read is one
+// indexed document and a decrypt — near enough free that memoizing it longer
+// buys nothing worth the staleness. The moment that actually matters is the one
+// right after an admin first types a credential in and goes looking for the
+// vendor to come alive: they are watching, and a minute is the longest that wait
+// should ever be.
+const MEMO_TTL_MS = 60 * 1000;
+
+// For tests. A save clears its own slug; this clears everything.
+const clearProviderMemo = () => providerMemo.clear();
+
+// Read a vendor's credentials, memoized, because this is on the path of every
 // OAuth callback and every send.
 //
 // An unconfigured vendor answers {} rather than throwing: the admin list has to
 // render the row that lets someone fix it.
 //
-// Thirty seconds rather than the default, so a credential rotated away stops
-// being served quickly.
-const providerSettings = async ({ cache, controller, slug }) => {
+// The memoized object is handed to every reader inside the window rather than
+// copied per read — no caller mutates its credentials, and defending against one
+// that does not exist would cost a clone on every send.
+const providerSettings = async ({ controller, slug }) => {
 
-	const read = async () => controller.get({
+	const memoized = providerMemo.get( slug );
+
+	if( memoized && Date.now() - memoized.at < MEMO_TTL_MS ) return memoized.value;
+
+	const row = await controller.get({
 		collection : 'provider',
 		query : { slug }
 	});
 
-	// OPTIONAL. drawbridge-webhooks has no Redis and reads these once at boot, so
-	// requiring a cache there would mean inventing one that never caches.
-	const row = cache ? await cache.use( cacheKey( slug ), read, 30 ) : await read();
+	const value = row?.settings ? decrypt( row.settings ) : {};
 
-	return row?.settings ? decrypt( row.settings ) : {};
+	providerMemo.set( slug, { at : Date.now(), value });
+
+	return value;
 
 };
 
@@ -168,7 +178,7 @@ const providerSettings = async ({ cache, controller, slug }) => {
 // BLANK MEANS KEEP. A redacted field is never returned by the GET, so an
 // unchanged form posts it back empty; treating that as a clear would wipe a
 // credential every time someone edited the field next to it.
-const saveProviderSettings = async ({ authenticated, cache, clear, controller, settings, slug }) => {
+const saveProviderSettings = async ({ authenticated, clear, controller, settings, slug }) => {
 
 	const fields = providerFields( slug );
 
@@ -217,33 +227,20 @@ const saveProviderSettings = async ({ authenticated, cache, clear, controller, s
 		query : { slug }
 	});
 
-	// AFTER the write rather than before it, which is the better of two
-	// imperfect orderings — busting first would guarantee a reader repopulates
-	// the old value.
+	// THE PROCESS THAT TOOK THE SAVE IS CORRECT IMMEDIATELY. Without this the
+	// admin who just typed the credential in reads back the list this same
+	// process memoized a moment ago and sees the vendor still not live, for up to
+	// a minute, with nothing to do about it.
 	//
-	// It does NOT close the race. cache.use is GET-miss, run callback,
-	// unconditional JSON.SET, with no compare-and-set: a reader whose read
-	// already returned the old row, and whose write lands after this delete,
-	// puts the pre-rotation credential back. The short TTL on the read is what
-	// bounds that — seconds, not the default — because this is the Redis all
-	// three services share and the value is a credential someone may have just
-	// rotated BECAUSE it leaked.
-	await cache.delete( cacheKey( slug ) );
+	// The other processes are not covered and do not need to be: their memos age
+	// out on their own within the window, which is the trade a per-process memo
+	// buys in exchange for never needing a bust to travel between services.
+	providerMemo.delete( slug );
 
 	return result;
 
 };
 
-// EVERY STORED CREDENTIAL, SHAPED LIKE AN ENVIRONMENT.
-//
-// Keyed by the env var each field replaces, because that is the shape the
-// manifests already speak: `requires` names env vars, and auth.oauth.client
-// names them too. Handing availableConnections this map instead of process.env
-// is the whole switch — the package does not change, and 137 call sites in this
-// repo keep reading a plain synchronous object.
-//
-// A field with no value is OMITTED rather than set empty, so `requires` sees
-// the same absence it would for an unset variable.
 // EVERY ENV NAME THE PROVIDER SCREEN OWNS.
 //
 // The boundary between "an admin types this in" and "the deployment supplies
@@ -254,64 +251,56 @@ const saveProviderSettings = async ({ authenticated, cache, clear, controller, s
 const providerEnvNames = () => new Set(
 	providerSlugs()
 		.flatMap( ( slug ) => providerFields( slug ) )
-		.map( ( field ) => field.env )
+		.map( ( field ) => field.credential )
 		.filter( Boolean )
 );
 
-const providerCredentials = async ({ cache, controller }) => {
+// EVERY STORED CREDENTIAL, KEYED BY ITS NAME.
+//
+// Keyed by each field's `credential`, because that is the vocabulary the
+// manifests already speak: `requires` names credentials, and auth.oauth.client
+// names them too. Handing availableConnections this map is what makes stored
+// credentials answer the question the manifests were already asking.
+//
+// A field with no value is OMITTED rather than set empty, so `requires` sees
+// the same absence it would for an unset variable.
+const providerCredentials = async ({ controller }) => {
 
 	const credentials = {};
 
 	for( const slug of providerSlugs() ){
 
-		const settings = await providerSettings({ cache, controller, slug });
+		// ONE BAD ROW COSTS ONE VENDOR. decrypt throws on a value that was written
+		// under a different ENCRYPT_CONNECTION_SECRET, and unguarded that throw
+		// escaped the whole loop — a single half-rotated row read as a platform
+		// with no SendGrid, no Twilio and no Shopify either, which is a far worse
+		// outage than the one it came from.
+		//
+		// Degrading to "that vendor is unconfigured" lands in a state the product
+		// already has an answer for: the admin screen renders the row as not live,
+		// which is exactly where someone goes to fix it.
+		try {
 
-		for( const field of providerFields( slug ) ){
+			const settings = await providerSettings({ controller, slug });
 
-			const value = settings?.[ field.key ];
+			for( const field of providerFields( slug ) ){
 
-			if( field.env && value ) credentials[ field.env ] = value;
+				const value = settings?.[ field.key ];
 
-		}
+				if( field.credential && value ) credentials[ field.credential ] = value;
 
-	}
-
-	return credentials;
-
-};
+			}
 
-// PUT THE STORED CREDENTIALS WHERE EVERYTHING ALREADY LOOKS.
-//
-// The apps are not the only readers. @drawbridge/shopify verifies every webhook
-// HMAC against process.env.SHOPIFY_API_SECRET, drawbridge-utils' own sendgrid
-// and twilio wrappers default to process.env, and drawbridge-sync freezes its
-// step→queue routing table from process.env at require time. Threading a
-// credentials object through all of that would be a sweep across three repos and
-// a published package, and every site it missed would fail silently.
-//
-// So the environment stays the transport and the collection becomes the SOURCE:
-// this writes the stored values into process.env before anything reads them.
-//
-// IT DELETES FIRST. Every name a provider field declares is removed whether or
-// not the database has a value for it, so a variable left behind in a deployment
-// cannot keep a vendor alive after its credential was taken out of the database
-// — which would leave the connection reading available and failing on use.
-// Names no provider declares are untouched: ENCRYPT_CONNECTION_SECRET is the
-// clearest case, since it is the key this collection is decrypted with and can
-// never be stored inside it.
-//
-// Returns the names it set, so a caller can log what it loaded without logging
-// what it loaded them to.
-const hydrateEnvironment = async ({ cache, controller, env = process.env }) => {
+		} catch {
 
-	const credentials = await providerCredentials({ cache, controller });
+			continue;
 
-	for( const name of providerEnvNames() ) delete env[ name ];
+		}
 
-	Object.assign( env, credentials );
+	}
 
-	return Object.keys( credentials ).sort();
+	return credentials;
 
 };
 
-export { cacheKey, hydrateEnvironment, isLive, mask, providerCredentials, providerEnvNames, providerFields, providerSettings, providerSlugs, saveProviderSettings };
+export { clearProviderMemo, isLive, mask, providerCredentials, providerEnvNames, providerFields, providerMemo, providerSettings, providerSlugs, saveProviderSettings };