@drawbridge/drawbridge-utils 0.0.111 → 0.0.114

package/dist/connections/oauth.cjs

@@ -19,19 +19,18 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // lib/connections/oauth.js
 var oauth_exports = {};
 __export(oauth_exports, {
+  authToken: () => authToken,
   consentUrl: () => consentUrl,
-  exchange: () => exchange,
-  pkcePair: () => pkcePair,
-  refresh: () => refresh
+  pkcePair: () => pkcePair
 });
 module.exports = __toCommonJS(oauth_exports);
 var import_node_crypto = require("crypto");
-var credentials = ({ clientId, clientSecret, descriptor }) => (descriptor == null ? void 0 : descriptor.clientAuth) === "basic" ? {
-  headers: { authorization: "Basic " + Buffer.from(clientId + ":" + clientSecret).toString("base64") },
-  body: {}
+var credentials = ({ basic, clientId, clientSecret }) => basic ? {
+  body: {},
+  headers: { authorization: "Basic " + Buffer.from(clientId + ":" + clientSecret).toString("base64") }
 } : {
-  headers: {},
-  body: { client_id: clientId, client_secret: clientSecret }
+  body: { client_id: clientId, client_secret: clientSecret },
+  headers: {}
 };
 var pkcePair = () => {
   const verifier = (0, import_node_crypto.randomBytes)(32).toString("base64url");
@@ -42,10 +41,11 @@ var pkcePair = () => {
   };
 };
 var consentUrl = ({ challenge, clientId, descriptor, redirect, state } = {}) => {
+  var _a;
   if (!clientId) throw new Error("This deployment has no OAuth client configured, so there is nothing to consent through");
-  if (!(descriptor == null ? void 0 : descriptor.authorize)) throw new Error("This connection declares no authorize url");
+  if (!((_a = descriptor == null ? void 0 : descriptor.urls) == null ? void 0 : _a.authorize)) throw new Error("This connection declares no authorize url");
   if (descriptor.pkce && !challenge) throw new Error("This connection requires PKCE, so a code challenge is not optional");
-  return descriptor.authorize + "?" + new URLSearchParams({
+  return descriptor.urls.authorize + "?" + new URLSearchParams({
     // The descriptor's own params go FIRST, so a vendor quirk cannot quietly
     // overwrite one of the fields below that every consent carries.
     ...descriptor.params || {},
@@ -60,17 +60,33 @@ var consentUrl = ({ challenge, clientId, descriptor, redirect, state } = {}) =>
     state
   });
 };
-var exchange = async ({ clientId, clientSecret, code, descriptor, fetcher = fetch, redirect, verifier } = {}) => {
-  if (!(descriptor == null ? void 0 : descriptor.token)) throw new Error("This connection declares no token url");
-  if (descriptor.pkce && !verifier) throw new Error("This connection requires PKCE, so the code verifier is not optional");
-  const client = credentials({ clientId, clientSecret, descriptor });
-  const response = await fetcher(descriptor.token, {
+var authToken = async ({
+  basic,
+  clientId,
+  clientSecret,
+  code,
+  descriptor,
+  fetcher = fetch,
+  redirect,
+  refreshToken,
+  verifier
+} = {}) => {
+  var _a;
+  if (!clientId || !clientSecret) throw new Error("This deployment has no OAuth client configured, so no token can be minted");
+  if (!((_a = descriptor == null ? void 0 : descriptor.urls) == null ? void 0 : _a.token)) throw new Error("This connection declares no token url");
+  const renewing = !code;
+  if (renewing && !refreshToken) throw new Error("Nothing has been consented to yet, so there is no refresh token to spend");
+  if (!renewing && descriptor.pkce && !verifier) throw new Error("This connection requires PKCE, so the code verifier is not optional");
+  const client = credentials({ basic, clientId, clientSecret });
+  const response = await fetcher(descriptor.urls.token, {
     body: new URLSearchParams({
       ...client.body,
-      code: decodeURIComponent(String(code || "").trim()),
-      grant_type: "authorization_code",
-      redirect_uri: redirect,
-      ...descriptor.pkce && { code_verifier: verifier }
+      ...renewing ? { grant_type: "refresh_token", refresh_token: refreshToken } : {
+        code: decodeURIComponent(String(code || "").trim()),
+        grant_type: "authorization_code",
+        redirect_uri: redirect,
+        ...descriptor.pkce && { code_verifier: verifier }
+      }
     }),
     headers: { "content-type": "application/x-www-form-urlencoded", ...client.headers },
     method: "POST",
@@ -78,46 +94,29 @@ var exchange = async ({ clientId, clientSecret, code, descriptor, fetcher = fetc
   });
   const body = await response.json().catch(() => ({}));
   if (!response.ok) {
-    throw new Error("The vendor refused the exchange (" + response.status + ")" + ((body == null ? void 0 : body.error) ? ": " + body.error : ""));
+    throw new Error(
+      renewing ? "The vendor refused the refresh token (" + response.status + ") \u2014 reconnect the connection" : "The vendor refused the exchange (" + response.status + ")" + ((body == null ? void 0 : body.error) ? ": " + body.error : "")
+    );
   }
-  if (!body.access_token) throw new Error("The vendor returned no access token");
+  if (!renewing && !body.access_token) throw new Error("The vendor returned no access token");
   return {
     accessToken: body.access_token,
     expiresIn: body.expires_in || null,
+    // A REFRESH TOKEN IS NOT UNIVERSAL. Google returns one only with
+    // access_type=offline; Mailchimp's tokens do not expire and it returns none
+    // at all, so its absence cannot be an error here.
+    //
+    // On a RENEWAL the same null matters for the opposite reason: a vendor that
+    // rotates returns a new one, and dropping it silently invalidates the stored
+    // grant on the NEXT refresh — a failure a day late and nowhere near its
+    // cause. tokenSettings() keeps the existing one when this is null.
     refreshToken: body.refresh_token || null,
     scope: body.scope || null
   };
 };
-var refresh = async ({ clientId, clientSecret, descriptor, fetcher = fetch, refreshToken } = {}) => {
-  if (!clientId || !clientSecret) throw new Error("This deployment has no OAuth client configured, so no token can be minted");
-  if (!refreshToken) throw new Error("Nothing has been consented to yet, so there is no refresh token to spend");
-  if (!(descriptor == null ? void 0 : descriptor.token)) throw new Error("This connection declares no token url");
-  const client = credentials({ clientId, clientSecret, descriptor });
-  const response = await fetcher(descriptor.token, {
-    body: new URLSearchParams({
-      ...client.body,
-      grant_type: "refresh_token",
-      refresh_token: refreshToken
-    }),
-    headers: { "content-type": "application/x-www-form-urlencoded", ...client.headers },
-    method: "POST",
-    signal: AbortSignal.timeout(15e3)
-  });
-  if (!response.ok) throw new Error("The vendor refused the refresh token (" + response.status + ") \u2014 reconnect the connection");
-  const body = await response.json();
-  return {
-    accessToken: body.access_token,
-    expiresIn: body.expires_in || null,
-    // A vendor that rotates its refresh token returns a new one, and dropping
-    // it silently invalidates the stored grant on the NEXT refresh rather
-    // than this one — a failure a day late and nowhere near its cause.
-    refreshToken: body.refresh_token || null
-  };
-};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  authToken,
   consentUrl,
-  exchange,
-  pkcePair,
-  refresh
+  pkcePair
 });

package/dist/connections/oauth.d.cts

@@ -2,19 +2,26 @@ import { randomBytes, createHash } from 'node:crypto';
 
 // HOW A VENDOR WANTS TO BE TOLD WHO WE ARE. Two conventions, both standard, and
 // vendors genuinely differ: Google takes client_id and client_secret as form
-// fields; Klaviyo requires HTTP Basic and rejects the body form. Declared per
-// vendor rather than branched on a slug, because the second Basic vendor would
-// otherwise add a second branch.
-const credentials = ({ clientId, clientSecret, descriptor }) => (
+// fields; Klaviyo requires HTTP Basic and rejects the body form.
+//
+// AN ARGUMENT, not a declared manifest key. It used to be
+// auth.oauth.client.headers, justified on the grounds that no hook calls a token
+// endpoint — which described a boundary rather than defending one. The manifest
+// already imported accessToken, so it was already reaching into this machinery,
+// and the flag existed only to configure the one request that was not a hook.
+//
+// Now the vendor passes it, in its own file, where the rest of what makes it
+// unusual already lives.
+const credentials = ({ basic, clientId, clientSecret }) => (
 
-	descriptor?.clientAuth === 'basic'
+	basic
 		? {
-			headers : { authorization : 'Basic ' + Buffer.from( clientId + ':' + clientSecret ).toString( 'base64' ) },
-			body : {}
+			body : {},
+			headers : { authorization : 'Basic ' + Buffer.from( clientId + ':' + clientSecret ).toString( 'base64' ) }
 		}
 		: {
-			headers : {},
-			body : { client_id : clientId, client_secret : clientSecret }
+			body : { client_id : clientId, client_secret : clientSecret },
+			headers : {}
 		}
 
 );
@@ -29,9 +36,9 @@ const credentials = ({ clientId, clientSecret, descriptor }) => (
 //   auth : {
 //       type  : 'oauth',
 //       oauth : {
-//           authorize : 'https://login.mailchimp.com/oauth2/authorize',
+//           urls : { authorize : 'https://login.mailchimp.com/oauth2/authorize',
 //           client    : { id : 'MAILCHIMP_OAUTH_CLIENT_ID', secret : 'MAILCHIMP_OAUTH_CLIENT_SECRET' },
-//           redirect  : '/api/connection/mailchimp/callback',
+//                    redirect  : '/api/connection/mailchimp/callback',
 //           token     : 'https://login.mailchimp.com/oauth2/token',
 //           params    : { ... },   optional vendor quirks
 //           pkce      : true,      Klaviyo's OAuth 2.1 requires it
@@ -76,11 +83,11 @@ const consentUrl = ({ challenge, clientId, descriptor, redirect, state } = {}) =
 	// fault nobody can fix from a connection page.
 	if( ! clientId ) throw new Error( 'This deployment has no OAuth client configured, so there is nothing to consent through' );
 
-	if( ! descriptor?.authorize ) throw new Error( 'This connection declares no authorize url' );
+	if( ! descriptor?.urls?.authorize ) throw new Error( 'This connection declares no authorize url' );
 
 	if( descriptor.pkce && ! challenge ) throw new Error( 'This connection requires PKCE, so a code challenge is not optional' );
 
-	return descriptor.authorize + '?' + new URLSearchParams({
+	return descriptor.urls.authorize + '?' + new URLSearchParams({
 		// The descriptor's own params go FIRST, so a vendor quirk cannot quietly
 		// overwrite one of the fields below that every consent carries.
 		...( descriptor.params || {} ),
@@ -97,26 +104,62 @@ const consentUrl = ({ challenge, clientId, descriptor, redirect, state } = {}) =
 
 };
 
-// The code-for-token trade.
+// THE DEFAULT auth.token — the standard OAuth token request, which is every
+// vendor's until one differs.
+//
+// A manifest declares hooks.auth.token like any other hook. Most point straight
+// here; Klaviyo wraps it to pass `basic`; Mailchimp will wrap it to follow with
+// the /oauth2/metadata call that tells it which data centre the account lives
+// behind. There is no dispatcher and no fallback, because the uniform surface
+// already forbids a manifest from staying silent — hooks.auth.token is always
+// answered, so there is never an absent case to branch on.
+//
+// Minting from a code and minting from a refresh token were two functions doing
+// the same POST to the same url with the same headers and the same response
+// mapping, differing only in body params and error copy — so they are one, and a
+// vendor overriding the call overrides both rather than remembering there were
+// two.
 //
 // The redirect must byte-match what the consent carried — it is registered in
 // the vendor's console — so the caller passes the declared callback and it is
 // used verbatim, never rebuilt from a slug.
-const exchange = async ({ clientId, clientSecret, code, descriptor, fetcher = fetch, redirect, verifier } = {}) => {
+//
+// `basic` is the vendor's to pass. `fetcher` is injected on every call so tests
+// never open a socket; production passes nothing and gets global fetch.
+const authToken = async ({
+	basic,
+	clientId,
+	clientSecret,
+	code,
+	descriptor,
+	fetcher = fetch,
+	redirect,
+	refreshToken,
+	verifier
+} = {}) => {
+
+	if( ! clientId || ! clientSecret ) throw new Error( 'This deployment has no OAuth client configured, so no token can be minted' );
+	if( ! descriptor?.urls?.token ) throw new Error( 'This connection declares no token url' );
 
-	if( ! descriptor?.token ) throw new Error( 'This connection declares no token url' );
+	const renewing = ! code;
 
-	if( descriptor.pkce && ! verifier ) throw new Error( 'This connection requires PKCE, so the code verifier is not optional' );
+	if( renewing && ! refreshToken ) throw new Error( 'Nothing has been consented to yet, so there is no refresh token to spend' );
+	if( ! renewing && descriptor.pkce && ! verifier ) throw new Error( 'This connection requires PKCE, so the code verifier is not optional' );
 
-	const client = credentials({ clientId, clientSecret, descriptor });
+	const client = credentials({ basic, clientId, clientSecret });
 
-	const response = await fetcher( descriptor.token, {
+	const response = await fetcher( descriptor.urls.token, {
 		body : new URLSearchParams({
 			...client.body,
-			code : decodeURIComponent( String( code || '' ).trim() ),
-			grant_type : 'authorization_code',
-			redirect_uri : redirect,
-			...( descriptor.pkce && { code_verifier : verifier })
+			...( renewing
+				? { grant_type : 'refresh_token', refresh_token : refreshToken }
+				: {
+					code : decodeURIComponent( String( code || '' ).trim() ),
+					grant_type : 'authorization_code',
+					redirect_uri : redirect,
+					...( descriptor.pkce && { code_verifier : verifier })
+				}
+			)
 		}),
 		headers : { 'content-type' : 'application/x-www-form-urlencoded', ...client.headers },
 		method : 'POST',
@@ -127,63 +170,33 @@ const exchange = async ({ clientId, clientSecret, code, descriptor, fetcher = fe
 
 	if( ! response.ok ){
 
-		throw new Error( 'The vendor refused the exchange (' + response.status + ')' + ( body?.error ? ': ' + body.error : '' ) );
+		// The two paths fail differently for the merchant: a refused exchange is
+		// "try connecting again", a refused refresh is "reconnect this connection",
+		// and collapsing them sends somebody to the wrong screen.
+		throw new Error( renewing
+			? 'The vendor refused the refresh token (' + response.status + ') — reconnect the connection'
+			: 'The vendor refused the exchange (' + response.status + ')' + ( body?.error ? ': ' + body.error : '' )
+		);
 
 	}
 
-	if( ! body.access_token ) throw new Error( 'The vendor returned no access token' );
+	if( ! renewing && ! body.access_token ) throw new Error( 'The vendor returned no access token' );
 
-	// A REFRESH TOKEN IS NOT UNIVERSAL. Google returns one only with
-	// access_type=offline; Mailchimp's tokens do not expire and it returns none
-	// at all. So its absence cannot be an error here the way it is in a
-	// refresh-only world — the manifest says whether the vendor issues one by
-	// whether it declares the params that ask for it.
 	return {
 		accessToken : body.access_token,
 		expiresIn : body.expires_in || null,
+		// A REFRESH TOKEN IS NOT UNIVERSAL. Google returns one only with
+		// access_type=offline; Mailchimp's tokens do not expire and it returns none
+		// at all, so its absence cannot be an error here.
+		//
+		// On a RENEWAL the same null matters for the opposite reason: a vendor that
+		// rotates returns a new one, and dropping it silently invalidates the stored
+		// grant on the NEXT refresh — a failure a day late and nowhere near its
+		// cause. tokenSettings() keeps the existing one when this is null.
 		refreshToken : body.refresh_token || null,
 		scope : body.scope || null
 	};
 
 };
 
-// Short-lived access, minted from a stored refresh token.
-//
-// THE MINT IS THE PROBE. A revoked, rotated or wrong-account grant fails here in
-// the vendor's own words, rather than as an empty result three steps later that
-// reads like "this account has no data".
-const refresh = async ({ clientId, clientSecret, descriptor, fetcher = fetch, refreshToken } = {}) => {
-
-	if( ! clientId || ! clientSecret ) throw new Error( 'This deployment has no OAuth client configured, so no token can be minted' );
-	if( ! refreshToken ) throw new Error( 'Nothing has been consented to yet, so there is no refresh token to spend' );
-	if( ! descriptor?.token ) throw new Error( 'This connection declares no token url' );
-
-	const client = credentials({ clientId, clientSecret, descriptor });
-
-	const response = await fetcher( descriptor.token, {
-		body : new URLSearchParams({
-			...client.body,
-			grant_type : 'refresh_token',
-			refresh_token : refreshToken
-		}),
-		headers : { 'content-type' : 'application/x-www-form-urlencoded', ...client.headers },
-		method : 'POST',
-		signal : AbortSignal.timeout( 15000 )
-	});
-
-	if( ! response.ok ) throw new Error( 'The vendor refused the refresh token (' + response.status + ') — reconnect the connection' );
-
-	const body = await response.json();
-
-	return {
-		accessToken : body.access_token,
-		expiresIn : body.expires_in || null,
-		// A vendor that rotates its refresh token returns a new one, and dropping
-		// it silently invalidates the stored grant on the NEXT refresh rather
-		// than this one — a failure a day late and nowhere near its cause.
-		refreshToken : body.refresh_token || null
-	};
-
-};
-
-export { consentUrl, exchange, pkcePair, refresh };
+export { authToken, consentUrl, pkcePair };

package/dist/connections/oauth.d.ts

@@ -2,19 +2,26 @@ import { randomBytes, createHash } from 'node:crypto';
 
 // HOW A VENDOR WANTS TO BE TOLD WHO WE ARE. Two conventions, both standard, and
 // vendors genuinely differ: Google takes client_id and client_secret as form
-// fields; Klaviyo requires HTTP Basic and rejects the body form. Declared per
-// vendor rather than branched on a slug, because the second Basic vendor would
-// otherwise add a second branch.
-const credentials = ({ clientId, clientSecret, descriptor }) => (
+// fields; Klaviyo requires HTTP Basic and rejects the body form.
+//
+// AN ARGUMENT, not a declared manifest key. It used to be
+// auth.oauth.client.headers, justified on the grounds that no hook calls a token
+// endpoint — which described a boundary rather than defending one. The manifest
+// already imported accessToken, so it was already reaching into this machinery,
+// and the flag existed only to configure the one request that was not a hook.
+//
+// Now the vendor passes it, in its own file, where the rest of what makes it
+// unusual already lives.
+const credentials = ({ basic, clientId, clientSecret }) => (
 
-	descriptor?.clientAuth === 'basic'
+	basic
 		? {
-			headers : { authorization : 'Basic ' + Buffer.from( clientId + ':' + clientSecret ).toString( 'base64' ) },
-			body : {}
+			body : {},
+			headers : { authorization : 'Basic ' + Buffer.from( clientId + ':' + clientSecret ).toString( 'base64' ) }
 		}
 		: {
-			headers : {},
-			body : { client_id : clientId, client_secret : clientSecret }
+			body : { client_id : clientId, client_secret : clientSecret },
+			headers : {}
 		}
 
 );
@@ -29,9 +36,9 @@ const credentials = ({ clientId, clientSecret, descriptor }) => (
 //   auth : {
 //       type  : 'oauth',
 //       oauth : {
-//           authorize : 'https://login.mailchimp.com/oauth2/authorize',
+//           urls : { authorize : 'https://login.mailchimp.com/oauth2/authorize',
 //           client    : { id : 'MAILCHIMP_OAUTH_CLIENT_ID', secret : 'MAILCHIMP_OAUTH_CLIENT_SECRET' },
-//           redirect  : '/api/connection/mailchimp/callback',
+//                    redirect  : '/api/connection/mailchimp/callback',
 //           token     : 'https://login.mailchimp.com/oauth2/token',
 //           params    : { ... },   optional vendor quirks
 //           pkce      : true,      Klaviyo's OAuth 2.1 requires it
@@ -76,11 +83,11 @@ const consentUrl = ({ challenge, clientId, descriptor, redirect, state } = {}) =
 	// fault nobody can fix from a connection page.
 	if( ! clientId ) throw new Error( 'This deployment has no OAuth client configured, so there is nothing to consent through' );
 
-	if( ! descriptor?.authorize ) throw new Error( 'This connection declares no authorize url' );
+	if( ! descriptor?.urls?.authorize ) throw new Error( 'This connection declares no authorize url' );
 
 	if( descriptor.pkce && ! challenge ) throw new Error( 'This connection requires PKCE, so a code challenge is not optional' );
 
-	return descriptor.authorize + '?' + new URLSearchParams({
+	return descriptor.urls.authorize + '?' + new URLSearchParams({
 		// The descriptor's own params go FIRST, so a vendor quirk cannot quietly
 		// overwrite one of the fields below that every consent carries.
 		...( descriptor.params || {} ),
@@ -97,26 +104,62 @@ const consentUrl = ({ challenge, clientId, descriptor, redirect, state } = {}) =
 
 };
 
-// The code-for-token trade.
+// THE DEFAULT auth.token — the standard OAuth token request, which is every
+// vendor's until one differs.
+//
+// A manifest declares hooks.auth.token like any other hook. Most point straight
+// here; Klaviyo wraps it to pass `basic`; Mailchimp will wrap it to follow with
+// the /oauth2/metadata call that tells it which data centre the account lives
+// behind. There is no dispatcher and no fallback, because the uniform surface
+// already forbids a manifest from staying silent — hooks.auth.token is always
+// answered, so there is never an absent case to branch on.
+//
+// Minting from a code and minting from a refresh token were two functions doing
+// the same POST to the same url with the same headers and the same response
+// mapping, differing only in body params and error copy — so they are one, and a
+// vendor overriding the call overrides both rather than remembering there were
+// two.
 //
 // The redirect must byte-match what the consent carried — it is registered in
 // the vendor's console — so the caller passes the declared callback and it is
 // used verbatim, never rebuilt from a slug.
-const exchange = async ({ clientId, clientSecret, code, descriptor, fetcher = fetch, redirect, verifier } = {}) => {
+//
+// `basic` is the vendor's to pass. `fetcher` is injected on every call so tests
+// never open a socket; production passes nothing and gets global fetch.
+const authToken = async ({
+	basic,
+	clientId,
+	clientSecret,
+	code,
+	descriptor,
+	fetcher = fetch,
+	redirect,
+	refreshToken,
+	verifier
+} = {}) => {
+
+	if( ! clientId || ! clientSecret ) throw new Error( 'This deployment has no OAuth client configured, so no token can be minted' );
+	if( ! descriptor?.urls?.token ) throw new Error( 'This connection declares no token url' );
 
-	if( ! descriptor?.token ) throw new Error( 'This connection declares no token url' );
+	const renewing = ! code;
 
-	if( descriptor.pkce && ! verifier ) throw new Error( 'This connection requires PKCE, so the code verifier is not optional' );
+	if( renewing && ! refreshToken ) throw new Error( 'Nothing has been consented to yet, so there is no refresh token to spend' );
+	if( ! renewing && descriptor.pkce && ! verifier ) throw new Error( 'This connection requires PKCE, so the code verifier is not optional' );
 
-	const client = credentials({ clientId, clientSecret, descriptor });
+	const client = credentials({ basic, clientId, clientSecret });
 
-	const response = await fetcher( descriptor.token, {
+	const response = await fetcher( descriptor.urls.token, {
 		body : new URLSearchParams({
 			...client.body,
-			code : decodeURIComponent( String( code || '' ).trim() ),
-			grant_type : 'authorization_code',
-			redirect_uri : redirect,
-			...( descriptor.pkce && { code_verifier : verifier })
+			...( renewing
+				? { grant_type : 'refresh_token', refresh_token : refreshToken }
+				: {
+					code : decodeURIComponent( String( code || '' ).trim() ),
+					grant_type : 'authorization_code',
+					redirect_uri : redirect,
+					...( descriptor.pkce && { code_verifier : verifier })
+				}
+			)
 		}),
 		headers : { 'content-type' : 'application/x-www-form-urlencoded', ...client.headers },
 		method : 'POST',
@@ -127,63 +170,33 @@ const exchange = async ({ clientId, clientSecret, code, descriptor, fetcher = fe
 
 	if( ! response.ok ){
 
-		throw new Error( 'The vendor refused the exchange (' + response.status + ')' + ( body?.error ? ': ' + body.error : '' ) );
+		// The two paths fail differently for the merchant: a refused exchange is
+		// "try connecting again", a refused refresh is "reconnect this connection",
+		// and collapsing them sends somebody to the wrong screen.
+		throw new Error( renewing
+			? 'The vendor refused the refresh token (' + response.status + ') — reconnect the connection'
+			: 'The vendor refused the exchange (' + response.status + ')' + ( body?.error ? ': ' + body.error : '' )
+		);
 
 	}
 
-	if( ! body.access_token ) throw new Error( 'The vendor returned no access token' );
+	if( ! renewing && ! body.access_token ) throw new Error( 'The vendor returned no access token' );
 
-	// A REFRESH TOKEN IS NOT UNIVERSAL. Google returns one only with
-	// access_type=offline; Mailchimp's tokens do not expire and it returns none
-	// at all. So its absence cannot be an error here the way it is in a
-	// refresh-only world — the manifest says whether the vendor issues one by
-	// whether it declares the params that ask for it.
 	return {
 		accessToken : body.access_token,
 		expiresIn : body.expires_in || null,
+		// A REFRESH TOKEN IS NOT UNIVERSAL. Google returns one only with
+		// access_type=offline; Mailchimp's tokens do not expire and it returns none
+		// at all, so its absence cannot be an error here.
+		//
+		// On a RENEWAL the same null matters for the opposite reason: a vendor that
+		// rotates returns a new one, and dropping it silently invalidates the stored
+		// grant on the NEXT refresh — a failure a day late and nowhere near its
+		// cause. tokenSettings() keeps the existing one when this is null.
 		refreshToken : body.refresh_token || null,
 		scope : body.scope || null
 	};
 
 };
 
-// Short-lived access, minted from a stored refresh token.
-//
-// THE MINT IS THE PROBE. A revoked, rotated or wrong-account grant fails here in
-// the vendor's own words, rather than as an empty result three steps later that
-// reads like "this account has no data".
-const refresh = async ({ clientId, clientSecret, descriptor, fetcher = fetch, refreshToken } = {}) => {
-
-	if( ! clientId || ! clientSecret ) throw new Error( 'This deployment has no OAuth client configured, so no token can be minted' );
-	if( ! refreshToken ) throw new Error( 'Nothing has been consented to yet, so there is no refresh token to spend' );
-	if( ! descriptor?.token ) throw new Error( 'This connection declares no token url' );
-
-	const client = credentials({ clientId, clientSecret, descriptor });
-
-	const response = await fetcher( descriptor.token, {
-		body : new URLSearchParams({
-			...client.body,
-			grant_type : 'refresh_token',
-			refresh_token : refreshToken
-		}),
-		headers : { 'content-type' : 'application/x-www-form-urlencoded', ...client.headers },
-		method : 'POST',
-		signal : AbortSignal.timeout( 15000 )
-	});
-
-	if( ! response.ok ) throw new Error( 'The vendor refused the refresh token (' + response.status + ') — reconnect the connection' );
-
-	const body = await response.json();
-
-	return {
-		accessToken : body.access_token,
-		expiresIn : body.expires_in || null,
-		// A vendor that rotates its refresh token returns a new one, and dropping
-		// it silently invalidates the stored grant on the NEXT refresh rather
-		// than this one — a failure a day late and nowhere near its cause.
-		refreshToken : body.refresh_token || null
-	};
-
-};
-
-export { consentUrl, exchange, pkcePair, refresh };
+export { authToken, consentUrl, pkcePair };