@drawbridge/drawbridge-utils 0.0.117 → 0.0.121

package/dist/providers.d.cts

@@ -0,0 +1,326 @@
+import { mergeSettings } from './connections/index.cjs';
+import { decrypt, encrypt } from './encrypt.cjs';
+import './connections/oauth.cjs';
+import 'node:crypto';
+import './http.cjs';
+import './pricing.cjs';
+import './plans.cjs';
+import './features.cjs';
+import './index.cjs';
+import 'currency-codes';
+import 'nanoid';
+import './color.cjs';
+import 'tinycolor2';
+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';
+import 'node:https';
+import './axios.cjs';
+import 'axios';
+import 'net';
+import 'crypto';
+import './token.cjs';
+
+// DRAWBRIDGE'S OWN CREDENTIALS for a vendor, as opposed to a merchant's.
+//
+// lib/connections is the merchant-facing catalogue; this is the platform side.
+// They stay apart deliberately — a separate collection is only worth having if
+// merchant data and platform secrets do not start sharing helpers.
+//
+// HERE RATHER THAN IN AN APP, because three of them need the same answer.
+// drawbridge-api serves the admin screen and resolves the catalogue,
+// drawbridge-sync refreshes OAuth tokens and sends every mail and SMS, and
+// drawbridge-webhooks verifies vendor signatures. A copy per repo is three
+// copies of a decrypt and three chances for one of them to read a credential
+// the others have already rotated away.
+
+
+// WHAT AN ADMIN TYPES IN, per vendor.
+//
+// `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.
+//
+// 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
+// the database before throwing.
+const providerFields = ( slug ) => Object.hasOwn( FIELDS, slug ) ? FIELDS[ slug ] : [];
+
+// The vendors an admin can configure, in a stable order.
+const providerSlugs = () => Object.keys( FIELDS ).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.
+const isLive = ( slug, settings ) => {
+
+	const fields = providerFields( slug );
+
+	if( ! fields.length ) return false;
+
+	return fields
+		.filter( ( field ) => field.required )
+		.every( ( field ) => Boolean( settings?.[ field.key ] ) );
+
+};
+
+// ENOUGH TO RECOGNISE A CREDENTIAL, never enough to use one.
+//
+// The value itself is never sent — this is computed here so the browser only
+// ever holds the mask. That is stricter than route/oauth.js, which decrypts
+// client secrets in full for its admin table, and the difference is deliberate:
+// these are PLATFORM credentials, so one leaked key is every organisation's
+// problem at once, and a value that reaches the browser reaches the query
+// cache, devtools and any error report with it.
+//
+// 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 < 16 ) return '••••••••';
+
+	return String( value ).slice( 0, 3 ) + '••••••••' + String( value ).slice( -4 );
+
+};
+
+// 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.
+//
+// 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 row = await controller.get({
+		collection : 'provider',
+		query : { slug }
+	});
+
+	const value = row?.settings ? decrypt( row.settings ) : {};
+
+	providerMemo.set( slug, { at : Date.now(), value });
+
+	return value;
+
+};
+
+// Write a vendor's credentials.
+//
+// ONLY THE DECLARED FIELDS. The body arrives over the wire, so anything in it
+// that no field declares is not ours to store — that is what keeps this route
+// from being able to reach `slug` or any other column.
+//
+// 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, clear, controller, settings, slug }) => {
+
+	const fields = providerFields( slug );
+
+	if( ! fields.length ) return null;
+
+	const existing = await controller.get({
+		collection : 'provider',
+		query : { slug }
+	});
+
+	const stored = existing?.settings ? decrypt( existing.settings ) : {};
+
+	// mergeSettings is the blank-keeps rule, already used for merchant
+	// connection settings in route/organization-connection.js — same behaviour,
+	// one implementation. The declared-field allowlist is the part that is ours:
+	// building `incoming` from `fields` is what stops anything the vendor does
+	// not declare reaching the document.
+	const merged = mergeSettings({
+		existing : stored,
+		incoming : Object.fromEntries( fields.map( ( field ) => [ field.key, settings?.[ field.key ] ] ) )
+	});
+
+	// CLEARING IS EXPLICIT, because blank already means keep and the two cannot
+	// be the same gesture. Without this there is no way to remove a credential
+	// at all: every empty box is read as "leave it alone".
+	//
+	// Filtered against the declarations like everything else, so `clear` cannot
+	// reach a key the vendor does not have.
+	for( const key of ( Array.isArray( clear ) ? clear : [] ) ){
+
+		if( fields.some( ( field ) => field.key === key ) ) delete merged[ key ];
+
+	}
+
+	const result = await controller.update({
+		authenticated,
+		collection : 'provider',
+		data : {
+			$set : {
+				settings : encrypt( merged )
+			}
+		},
+		options : {
+			upsert : true
+		},
+		query : { slug }
+	});
+
+	// 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.
+	//
+	// 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 ENV NAME THE PROVIDER SCREEN OWNS.
+//
+// The boundary between "an admin types this in" and "the deployment supplies
+// it". ENCRYPT_CONNECTION_SECRET is the clearest case of the latter: the webhook
+// connection requires it, and it can never be stored here because it is the key
+// that decrypts this collection. Names outside this set keep coming from the
+// environment.
+const providerEnvNames = () => new Set(
+	providerSlugs()
+		.flatMap( ( slug ) => providerFields( slug ) )
+		.map( ( field ) => field.env )
+		.filter( Boolean )
+);
+
+// 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() ){
+
+		// 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 settings = await providerSettings({ controller, slug });
+
+			for( const field of providerFields( slug ) ){
+
+				const value = settings?.[ field.key ];
+
+				if( field.env && value ) credentials[ field.env ] = value;
+
+			}
+
+		} catch {
+
+			continue;
+
+		}
+
+	}
+
+	return credentials;
+
+};
+
+export { clearProviderMemo, isLive, mask, providerCredentials, providerEnvNames, providerFields, providerMemo, providerSettings, providerSlugs, saveProviderSettings };

package/dist/providers.d.ts

@@ -0,0 +1,326 @@
+import { mergeSettings } from './connections/index.js';
+import { decrypt, encrypt } from './encrypt.js';
+import './connections/oauth.js';
+import 'node:crypto';
+import './http.js';
+import './pricing.js';
+import './plans.js';
+import './features.js';
+import './index.js';
+import 'currency-codes';
+import 'nanoid';
+import './color.js';
+import 'tinycolor2';
+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';
+import 'node:https';
+import './axios.js';
+import 'axios';
+import 'net';
+import 'crypto';
+import './token.js';
+
+// DRAWBRIDGE'S OWN CREDENTIALS for a vendor, as opposed to a merchant's.
+//
+// lib/connections is the merchant-facing catalogue; this is the platform side.
+// They stay apart deliberately — a separate collection is only worth having if
+// merchant data and platform secrets do not start sharing helpers.
+//
+// HERE RATHER THAN IN AN APP, because three of them need the same answer.
+// drawbridge-api serves the admin screen and resolves the catalogue,
+// drawbridge-sync refreshes OAuth tokens and sends every mail and SMS, and
+// drawbridge-webhooks verifies vendor signatures. A copy per repo is three
+// copies of a decrypt and three chances for one of them to read a credential
+// the others have already rotated away.
+
+
+// WHAT AN ADMIN TYPES IN, per vendor.
+//
+// `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.
+//
+// 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
+// the database before throwing.
+const providerFields = ( slug ) => Object.hasOwn( FIELDS, slug ) ? FIELDS[ slug ] : [];
+
+// The vendors an admin can configure, in a stable order.
+const providerSlugs = () => Object.keys( FIELDS ).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.
+const isLive = ( slug, settings ) => {
+
+	const fields = providerFields( slug );
+
+	if( ! fields.length ) return false;
+
+	return fields
+		.filter( ( field ) => field.required )
+		.every( ( field ) => Boolean( settings?.[ field.key ] ) );
+
+};
+
+// ENOUGH TO RECOGNISE A CREDENTIAL, never enough to use one.
+//
+// The value itself is never sent — this is computed here so the browser only
+// ever holds the mask. That is stricter than route/oauth.js, which decrypts
+// client secrets in full for its admin table, and the difference is deliberate:
+// these are PLATFORM credentials, so one leaked key is every organisation's
+// problem at once, and a value that reaches the browser reaches the query
+// cache, devtools and any error report with it.
+//
+// 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 < 16 ) return '••••••••';
+
+	return String( value ).slice( 0, 3 ) + '••••••••' + String( value ).slice( -4 );
+
+};
+
+// 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.
+//
+// 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 row = await controller.get({
+		collection : 'provider',
+		query : { slug }
+	});
+
+	const value = row?.settings ? decrypt( row.settings ) : {};
+
+	providerMemo.set( slug, { at : Date.now(), value });
+
+	return value;
+
+};
+
+// Write a vendor's credentials.
+//
+// ONLY THE DECLARED FIELDS. The body arrives over the wire, so anything in it
+// that no field declares is not ours to store — that is what keeps this route
+// from being able to reach `slug` or any other column.
+//
+// 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, clear, controller, settings, slug }) => {
+
+	const fields = providerFields( slug );
+
+	if( ! fields.length ) return null;
+
+	const existing = await controller.get({
+		collection : 'provider',
+		query : { slug }
+	});
+
+	const stored = existing?.settings ? decrypt( existing.settings ) : {};
+
+	// mergeSettings is the blank-keeps rule, already used for merchant
+	// connection settings in route/organization-connection.js — same behaviour,
+	// one implementation. The declared-field allowlist is the part that is ours:
+	// building `incoming` from `fields` is what stops anything the vendor does
+	// not declare reaching the document.
+	const merged = mergeSettings({
+		existing : stored,
+		incoming : Object.fromEntries( fields.map( ( field ) => [ field.key, settings?.[ field.key ] ] ) )
+	});
+
+	// CLEARING IS EXPLICIT, because blank already means keep and the two cannot
+	// be the same gesture. Without this there is no way to remove a credential
+	// at all: every empty box is read as "leave it alone".
+	//
+	// Filtered against the declarations like everything else, so `clear` cannot
+	// reach a key the vendor does not have.
+	for( const key of ( Array.isArray( clear ) ? clear : [] ) ){
+
+		if( fields.some( ( field ) => field.key === key ) ) delete merged[ key ];
+
+	}
+
+	const result = await controller.update({
+		authenticated,
+		collection : 'provider',
+		data : {
+			$set : {
+				settings : encrypt( merged )
+			}
+		},
+		options : {
+			upsert : true
+		},
+		query : { slug }
+	});
+
+	// 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.
+	//
+	// 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 ENV NAME THE PROVIDER SCREEN OWNS.
+//
+// The boundary between "an admin types this in" and "the deployment supplies
+// it". ENCRYPT_CONNECTION_SECRET is the clearest case of the latter: the webhook
+// connection requires it, and it can never be stored here because it is the key
+// that decrypts this collection. Names outside this set keep coming from the
+// environment.
+const providerEnvNames = () => new Set(
+	providerSlugs()
+		.flatMap( ( slug ) => providerFields( slug ) )
+		.map( ( field ) => field.env )
+		.filter( Boolean )
+);
+
+// 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() ){
+
+		// 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 settings = await providerSettings({ controller, slug });
+
+			for( const field of providerFields( slug ) ){
+
+				const value = settings?.[ field.key ];
+
+				if( field.env && value ) credentials[ field.env ] = value;
+
+			}
+
+		} catch {
+
+			continue;
+
+		}
+
+	}
+
+	return credentials;
+
+};
+
+export { clearProviderMemo, isLive, mask, providerCredentials, providerEnvNames, providerFields, providerMemo, providerSettings, providerSlugs, saveProviderSettings };