@drawbridge/drawbridge-utils 0.0.118 → 0.0.121

package/dist/providers.d.cts

@@ -15,6 +15,9 @@ import './usage.cjs';
 import './billing.cjs';
 import './transactions.cjs';
 import '@drawbridge/drawbridge-telemetry';
+import './email.cjs';
+import './phone.cjs';
+import 'libphonenumber-js';
 import './safe-http.cjs';
 import 'dns';
 import 'node:http';
@@ -120,42 +123,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 memoized = providerMemo.get( slug );
+
+	if( memoized && Date.now() - memoized.at < MEMO_TTL_MS ) return memoized.value;
 
-	const read = async () => controller.get({
+	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 +197,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 +246,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
@@ -258,60 +274,53 @@ const providerEnvNames = () => new Set(
 		.filter( Boolean )
 );
 
-const providerCredentials = async ({ cache, controller }) => {
+// 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.
+const providerCredentials = async ({ controller }) => {
 
 	const credentials = {};
 
 	for( const slug of providerSlugs() ){
 
-		const settings = await providerSettings({ cache, controller, slug });
-
-		for( const field of providerFields( 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 {
 
-			const value = settings?.[ field.key ];
+			const settings = await providerSettings({ controller, slug });
 
-			if( field.env && value ) credentials[ field.env ] = value;
+			for( const field of providerFields( slug ) ){
 
-		}
-
-	}
+				const value = settings?.[ field.key ];
 
-	return credentials;
+				if( field.env && value ) credentials[ field.env ] = value;
 
-};
+			}
 
-// 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 };

package/dist/providers.d.ts

@@ -15,6 +15,9 @@ import './usage.js';
 import './billing.js';
 import './transactions.js';
 import '@drawbridge/drawbridge-telemetry';
+import './email.js';
+import './phone.js';
+import 'libphonenumber-js';
 import './safe-http.js';
 import 'dns';
 import 'node:http';
@@ -120,42 +123,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 memoized = providerMemo.get( slug );
+
+	if( memoized && Date.now() - memoized.at < MEMO_TTL_MS ) return memoized.value;
 
-	const read = async () => controller.get({
+	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 +197,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 +246,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
@@ -258,60 +274,53 @@ const providerEnvNames = () => new Set(
 		.filter( Boolean )
 );
 
-const providerCredentials = async ({ cache, controller }) => {
+// 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.
+const providerCredentials = async ({ controller }) => {
 
 	const credentials = {};
 
 	for( const slug of providerSlugs() ){
 
-		const settings = await providerSettings({ cache, controller, slug });
-
-		for( const field of providerFields( 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 {
 
-			const value = settings?.[ field.key ];
+			const settings = await providerSettings({ controller, slug });
 
-			if( field.env && value ) credentials[ field.env ] = value;
+			for( const field of providerFields( slug ) ){
 
-		}
-
-	}
+				const value = settings?.[ field.key ];
 
-	return credentials;
+				if( field.env && value ) credentials[ field.env ] = value;
 
-};
+			}
 
-// 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 };