@drawbridge/drawbridge-utils 0.0.116 → 0.0.118

package/dist/providers.d.cts

@@ -0,0 +1,317 @@
+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 './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.
+const mask = ( value ) => {
+
+	if( ! value ) return null;
+
+	if( String( value ).length < 12 ) 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
+// 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 }) => {
+
+	const read = async () => 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();
+
+	return row?.settings ? decrypt( row.settings ) : {};
+
+};
+
+// 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, cache, 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 }
+	});
+
+	// 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.
+	//
+	// 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 ) );
+
+	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
+// 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 )
+);
+
+const providerCredentials = async ({ cache, controller }) => {
+
+	const credentials = {};
+
+	for( const slug of providerSlugs() ){
+
+		const settings = await providerSettings({ cache, controller, slug });
+
+		for( const field of providerFields( slug ) ){
+
+			const value = settings?.[ field.key ];
+
+			if( field.env && value ) credentials[ field.env ] = 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 }) => {
+
+	const credentials = await providerCredentials({ cache, controller });
+
+	for( const name of providerEnvNames() ) delete env[ name ];
+
+	Object.assign( env, credentials );
+
+	return Object.keys( credentials ).sort();
+
+};
+
+export { cacheKey, hydrateEnvironment, isLive, mask, providerCredentials, providerEnvNames, providerFields, providerSettings, providerSlugs, saveProviderSettings };

package/dist/providers.d.ts

@@ -0,0 +1,317 @@
+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 './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.
+const mask = ( value ) => {
+
+	if( ! value ) return null;
+
+	if( String( value ).length < 12 ) 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
+// 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 }) => {
+
+	const read = async () => 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();
+
+	return row?.settings ? decrypt( row.settings ) : {};
+
+};
+
+// 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, cache, 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 }
+	});
+
+	// 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.
+	//
+	// 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 ) );
+
+	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
+// 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 )
+);
+
+const providerCredentials = async ({ cache, controller }) => {
+
+	const credentials = {};
+
+	for( const slug of providerSlugs() ){
+
+		const settings = await providerSettings({ cache, controller, slug });
+
+		for( const field of providerFields( slug ) ){
+
+			const value = settings?.[ field.key ];
+
+			if( field.env && value ) credentials[ field.env ] = 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 }) => {
+
+	const credentials = await providerCredentials({ cache, controller });
+
+	for( const name of providerEnvNames() ) delete env[ name ];
+
+	Object.assign( env, credentials );
+
+	return Object.keys( credentials ).sort();
+
+};
+
+export { cacheKey, hydrateEnvironment, isLive, mask, providerCredentials, providerEnvNames, providerFields, providerSettings, providerSlugs, saveProviderSettings };