@mcp-abap-adt/auth-broker 3.1.0 → 4.1.0

package/dist/AuthBroker.js

@@ -1,6 +1,16 @@
 "use strict";
 /**
- * AuthBroker: tokens for a destination, from a provider, kept in a session store.
+ * AuthBroker: the credential for a destination, and tokens for one.
+ *
+ * `getProvider` builds the `IAuthProvider` a destination states, from the
+ * means its service key store holds and the secret its session store holds.
+ * Every token provider it builds writes what it obtains back to the session
+ * store through `onTokens` — the secret alone, retried by the broker when the
+ * store fails (`SessionWriter`); `flush()` reports what is still pending.
+ * The token API (`getToken`, `refreshToken`, `createTokenRefresher`) asks that
+ * same provider — one per destination, shared — or, when the consumer gives
+ * one, the consumer's provider, whose every answer it writes through the same
+ * path.
  *
  * The broker orchestrates and nothing more. It resolves what the stores know
  * about a destination, hands it to the provider, asks the provider for a token
@@ -12,12 +22,111 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AuthBroker = void 0;
 const interfaces_auth_1 = require("@mcp-abap-adt/interfaces-auth");
+const binding_1 = require("./binding");
+const bindingOf_1 = require("./bindingOf");
+const clientAuthentication_1 = require("./clientAuthentication");
+const DestinationConfigError_1 = require("./DestinationConfigError");
+const destinations_1 = require("./destinations");
+const SessionWriter_1 = require("./SessionWriter");
 const noOpLogger = {
     info: () => { },
     error: () => { },
     warn: () => { },
     debug: () => { },
 };
+/** The session secret's fields on a connection config — never means. */
+/** The session's side: the secret and what it is bound to. */
+const SECRET_FIELDS = [
+    'authorizationToken',
+    'sessionCookies',
+    'expiresAt',
+    'issuedFor',
+    'issuedBy',
+];
+const isSecretField = (field) => SECRET_FIELDS.includes(field);
+/**
+ * The connection means a strategy-path seed carries — the connection's own,
+ * none of them a secret. Everything else a store's connection read answers
+ * (credentials, grant data, fields outside the type) stays behind.
+ */
+const SEED_MEANS = [
+    'serviceUrl',
+    'sapClient',
+    'language',
+    'authType',
+    'grantType',
+];
+/**
+ * The token API factory's seed on the `clientAuthentication` strategy path,
+ * from an allowlist only: `SEED_MEANS`, and the session secret's own fields
+ * (`SECRET_FIELDS`: the token or cookies, the expiry, the binding) only when
+ * that same read is bound here — each secret judged by the read it came from.
+ * `serviceUrl` is the one resolved for the destination.
+ */
+function strategySeed(connConfig, binding, serviceUrl) {
+    const source = (connConfig ?? {});
+    const fields = connConfig && (0, binding_1.boundHere)(connConfig, binding)
+        ? [...SEED_MEANS, ...SECRET_FIELDS]
+        : SEED_MEANS;
+    const seed = {};
+    for (const field of fields) {
+        if (source[field] !== undefined)
+            seed[field] = source[field];
+    }
+    return { ...seed, serviceUrl };
+}
+/** When the result expires, in epoch ms: its own `expiresAt`, else `expiresIn` from now. */
+function expiryOf(result) {
+    if (typeof result.expiresAt === 'number')
+        return result.expiresAt;
+    if (typeof result.expiresIn === 'number') {
+        return Date.now() + Math.round(result.expiresIn * 1000);
+    }
+    return undefined;
+}
+/** A provider `getProvider` built that obtains tokens: a token provider. */
+function obtainsTokens(provider) {
+    const candidate = provider;
+    return (typeof candidate.getTokens === 'function' &&
+        typeof candidate.refreshTokens === 'function');
+}
+/** The refresh token a stored session holds, unchecked. */
+function storedRefreshTokenOf(session) {
+    return typeof session?.refreshToken === 'string'
+        ? session.refreshToken
+        : undefined;
+}
+/**
+ * The 3.x composition, the no-strategy path: the session's client as it is,
+ * else the key store's with `refreshToken` — the one given, else the key's
+ * own. (The strategy path takes `strategyAuthorization`.)
+ */
+function composeAuthorization(read, refreshToken) {
+    if (read.sessionAuth)
+        return read.sessionAuth;
+    if (!read.keyAuth)
+        return null;
+    return {
+        ...read.keyAuth,
+        refreshToken: refreshToken ?? read.keyAuth.refreshToken,
+    };
+}
+/**
+ * The client on the `clientAuthentication` strategy path: the session's own
+ * client, else the key store's, carrying only `refreshToken` — the one the
+ * session read whose binding was checked holds, when bound — never a refresh
+ * token either client read carried itself.
+ */
+function strategyAuthorization(read, refreshToken) {
+    // The same allowlist the strategy is told (`contextClient`): nothing else a
+    // store's authorization-config read carried reaches the factory.
+    const client = (0, clientAuthentication_1.contextClient)(read.sessionAuth ?? read.keyAuth);
+    return client ? { ...client, refreshToken } : null;
+}
+/** A stored string that counts as present: `''` is none. */
+function present(value) {
+    return typeof value === 'string' && value !== '';
+}
 function errorCode(error) {
     if (error !== null && typeof error === 'object' && 'code' in error) {
         const code = error.code;
@@ -25,6 +134,13 @@ function errorCode(error) {
     }
     return undefined;
 }
+/** A result carrying a token, or the 3.x error for one that carries none. */
+function checked(destination, result) {
+    if (!result?.authorizationToken) {
+        throw new Error(`Token provider did not return authorization token for destination "${destination}"`);
+    }
+    return result;
+}
 /**
  * AuthBroker manages authentication tokens for destinations
  */
@@ -33,7 +149,30 @@ class AuthBroker {
     serviceKeyStore;
     sessionStore;
     provider;
-    providers = new Map();
+    /** A consumer factory's providers: the promise of the build, as `built`. */
+    consumerBuilt = new Map();
+    /**
+     * One cache per destination, shared by `getProvider` and — when the
+     * consumer gives no provider — the token API: the promise of the
+     * build, set before its first read.
+     */
+    built = new Map();
+    /**
+     * The write that failed for a result, keyed on the result the provider
+     * handed over and returns, then on the destination it was written
+     * for: the token API throws it to its caller, as 3.x did, while the broker
+     * keeps retrying. Dropped once a write of that result for that destination
+     * lands.
+     */
+    failedWrites = new WeakMap();
+    authorization;
+    oidcAuthorization;
+    deviceCodePresenter;
+    samlCookies;
+    assertionReplayStore;
+    clientAuthentication;
+    /** getProvider's writes of the session secret, retried on their own. */
+    writer;
     /**
      * @param config Stores and the provider (instance or factory)
      * @param logger Optional logger. Nothing the broker logs contains a token.
@@ -46,9 +185,6 @@ class AuthBroker {
         if (!sessionStore) {
             throw new Error('AuthBroker: sessionStore is required');
         }
-        if (!provider) {
-            throw new Error('AuthBroker: provider is required');
-        }
         for (const method of [
             'getAuthorizationConfig',
             'getConnectionConfig',
@@ -61,7 +197,7 @@ class AuthBroker {
                 throw new Error(`AuthBroker: sessionStore.${method} must be a function`);
             }
         }
-        if (typeof provider !== 'function') {
+        if (provider && typeof provider !== 'function') {
             if (typeof provider.getTokens !== 'function') {
                 throw new Error('AuthBroker: provider.getTokens must be a function');
             }
@@ -83,91 +219,303 @@ class AuthBroker {
         this.sessionStore = sessionStore;
         this.serviceKeyStore = serviceKeyStore;
         this.provider = provider;
+        this.authorization = config.authorization;
+        this.oidcAuthorization = config.oidcAuthorization;
+        this.deviceCodePresenter = config.deviceCodePresenter;
+        this.samlCookies = config.samlCookies;
+        this.assertionReplayStore = config.assertionReplayStore;
+        this.clientAuthentication = config.clientAuthentication;
         this.logger = logger ?? noOpLogger;
+        this.writer = new SessionWriter_1.SessionWriter(async (destination, bound) => {
+            try {
+                await this.writeSecret(destination, bound);
+            }
+            catch (error) {
+                // Per destination: one result object may be answered for several
+                // (an instance serves every destination), and a write that lands for
+                // one says nothing about another's.
+                let failures = this.failedWrites.get(bound.original);
+                if (!failures) {
+                    failures = new Map();
+                    this.failedWrites.set(bound.original, failures);
+                }
+                failures.set(destination, { error });
+                throw error;
+            }
+            this.failedWrites.get(bound.original)?.delete(destination);
+        }, this.logger);
         this.logger.debug('[AuthBroker] Broker initialized', {
             hasServiceKeyStore: !!serviceKeyStore,
-            providerForm: typeof provider === 'function' ? 'factory' : 'instance',
+            providerForm: provider === undefined
+                ? 'none'
+                : typeof provider === 'function'
+                    ? 'factory'
+                    : 'instance',
         });
     }
     /**
      * A token for the destination: the provider's current one, which it refreshes
      * or obtains by login when it judges the cached one unusable.
      *
-     * The result is written to the session store. Errors from the provider
-     * (its typed errors included) propagate unchanged.
+     * Without a consumer `provider`, the provider is the one `getProvider` hands
+     * out for the destination — the same instance, so one token and one renewal
+     * serve both — and what it obtains is written by its `onTokens`. With one,
+     * the consumer's provider is asked and its answer written, as in 3.x — the
+     * secret alone.
+     *
+     * Errors from the provider (its typed errors included) propagate unchanged;
+     * so does a store failure, a failed write of the token included — the token
+     * stands and the broker keeps retrying the write.
+     *
+     * @throws DestinationConfigError for a destination the key store states as
+     *   `basic` or `snc`, before any provider is asked; without a consumer
+     *   `provider`, also for one whose provider obtains no token.
      */
     async getToken(destination) {
         return this.obtain(destination, 'getTokens');
     }
     /**
      * A new token for the destination, never the cached one — for a caller whose
-     * token the server has just refused. Calls the provider's `refreshTokens()`,
-     * writes the result to the session store and returns it.
+     * token the server has just refused. Calls the provider's `refreshTokens()`;
+     * a renewal already in flight for the destination is joined, not repeated.
      */
     async refreshToken(destination) {
         return this.obtain(destination, 'refreshTokens');
     }
     async obtain(destination, method) {
+        const means = await this.statedForTokens(destination);
+        const result = this.provider
+            ? await this.obtainFromConsumer(destination, method, means)
+            : await this.obtainShared(destination, method, means);
+        return result.authorizationToken;
+    }
+    /**
+     * The destination's means, read first: a destination the key store states
+     * as `basic` or `snc` holds no token, so the token API refuses it before any
+     * provider is asked — it would write a token over a credential that is not
+     * one. A key store that states no `authType`, or no key store, is
+     * a 3.x setup, served as before.
+     */
+    async statedForTokens(destination) {
+        const serviceKeyStore = this.serviceKeyStore;
+        const means = serviceKeyStore
+            ? await this.read(destination, 'service key connection config', () => serviceKeyStore.getConnectionConfig(destination))
+            : null;
+        const authType = means?.authType;
+        if (authType === 'basic' || authType === 'snc') {
+            throw new DestinationConfigError_1.DestinationConfigError(destination, ['authType'], `the token API serves no ${authType} destination: it holds no token`);
+        }
+        return means;
+    }
+    /** The token API on `getProvider`'s provider. */
+    async obtainShared(destination, method, means) {
+        if (!this.serviceKeyStore) {
+            throw new DestinationConfigError_1.DestinationConfigError(destination, ['provider', 'serviceKeyStore'], 'the token API needs the provider option, or a service key store stating a token grant');
+        }
+        if ((means?.authType === 'jwt' || means?.authType === 'saml') &&
+            means.grantType === 'none') {
+            throw new DestinationConfigError_1.DestinationConfigError(destination, ['provider'], 'a none destination presents a handed-over credential and obtains no token: use getProvider, or give the token API the provider option');
+        }
+        const provider = await this.getProvider(destination);
+        if (!obtainsTokens(provider)) {
+            throw new DestinationConfigError_1.DestinationConfigError(destination, ['provider'], 'the destination states a credential that obtains no token: use getProvider, or give the token API the provider option');
+        }
+        this.logger.debug(`[AuthBroker] ${method} for ${destination}`);
+        const result = checked(destination, await provider[method]());
+        // onTokens wrote it, or failed to: the failure is this caller's too.
+        this.throwFailedWrite(destination, result);
+        return result;
+    }
+    /**
+     * The token API on the consumer's provider, as 3.x: the session read first,
+     * then the key store, for `serviceUrl` and the client; every answer — a
+     * cache hit included — written, the secret alone, through the broker's one
+     * write path.
+     */
+    async obtainFromConsumer(destination, method, means) {
         const connConfig = await this.read(destination, 'session connection config', () => this.sessionStore.getConnectionConfig(destination));
         const serviceUrl = await this.resolveServiceUrl(destination, connConfig);
-        const provider = await this.providerFor(destination, serviceUrl, connConfig);
+        const { provider, binding, carry } = await this.consumerProviderFor(destination, serviceUrl, connConfig, means);
         this.logger.debug(`[AuthBroker] ${method} for ${destination}`);
-        const result = await provider[method]();
-        if (!result?.authorizationToken) {
-            throw new Error(`Token provider did not return authorization token for destination "${destination}"`);
+        const result = checked(destination, await provider[method]());
+        await this.writer.submit(destination, {
+            result: { ...result, expiresAt: expiryOf(result) },
+            original: result,
+            binding,
+            carry,
+        });
+        this.throwFailedWrite(destination, result);
+        return result;
+    }
+    /** The failure recorded for this result's write here, thrown as the store raised it. */
+    throwFailedWrite(destination, result) {
+        const failed = this.failedWrites.get(result)?.get(destination);
+        if (failed) {
+            throw failed.error;
         }
-        await this.persist(destination, serviceUrl, connConfig, result);
-        return result.authorizationToken;
     }
-    async providerFor(destination, serviceUrl, connConfig) {
-        if (typeof this.provider !== 'function') {
-            return this.provider;
-        }
-        const existing = this.providers.get(destination);
-        if (existing) {
-            return existing;
-        }
-        const authConfig = await this.resolveAuthorizationConfig(destination);
-        const built = this.provider(destination, authConfig, {
-            ...(connConfig ?? {}),
-            serviceUrl,
+    /**
+     * The consumer's provider for the destination, cached per destination as a
+     * promise set before its first read and dropped when it throws, so
+     * the next call builds again: a factory's build — handed the client resolved
+     * then — or an instance as given, for every destination, handed no client.
+     * Either way the binding is fixed here, from the `serviceUrl`, SAP client and
+     * client of this first call, and kept with the provider.
+     */
+    consumerProviderFor(destination, serviceUrl, connConfig, means) {
+        const cached = this.consumerBuilt.get(destination);
+        if (cached) {
+            return cached;
+        }
+        const provider = this.provider;
+        const sapClient = present(connConfig?.sapClient)
+            ? connConfig.sapClient
+            : means?.sapClient;
+        const build = Promise.resolve().then(async () => {
+            if (typeof provider !== 'function') {
+                return {
+                    provider,
+                    binding: (0, binding_1.consumerBinding)(serviceUrl, sapClient, null),
+                    carry: 'any',
+                };
+            }
+            const read = await this.readAuthorization(destination);
+            const strategic = await this.consumerClientAuthentication(destination, means, 
+            // The strategy is told the client, never a refresh token read with it.
+            strategyAuthorization(read, undefined));
+            let built;
+            let client;
+            let binding;
+            let carry;
+            if (strategic) {
+                // The strategy's answer and the client identity, resolved before the
+                // factory; the factory called inside the same guard: a throw is fixed
+                // words, nothing of the thrown value, no cause. The stored refresh
+                // token is carried only when the session is bound to this resource
+                // and this client identity — never to another authorization server.
+                binding = (0, binding_1.strategyBinding)((0, binding_1.consumerBinding)(serviceUrl, sapClient, strategic.identity));
+                const session = read.sessionRead
+                    ? read.session
+                    : await this.loadStoredSession(destination);
+                const bound = !!session && (0, binding_1.boundHere)(session, binding);
+                const boundRefreshToken = bound
+                    ? storedRefreshTokenOf(session)
+                    : undefined;
+                // The client without any refresh token of its own read: a session
+                // store's `getAuthorizationConfig` is another read than the session
+                // whose binding was checked, and another process may have written
+                // between them. The refresh token comes only from that checked read.
+                client = strategyAuthorization(read, boundRefreshToken);
+                // Each stored secret is judged by the read it came from: the seed's
+                // token, cookies and expiry by the binding the connection read itself
+                // carries — another process may have written between the two reads —
+                // else only the means seed the provider.
+                const seed = strategySeed(connConfig, binding, serviceUrl);
+                carry = 'bound';
+                const refreshToken = client ? client.refreshToken : boundRefreshToken;
+                const fourth = {
+                    clientAuthentication: strategic.clientAuthentication,
+                    ...(strategic.identity
+                        ? {
+                            uaaUrl: strategic.identity.uaaUrl,
+                            clientId: strategic.identity.uaaClientId,
+                        }
+                        : {}),
+                    ...(present(refreshToken) ? { refreshToken } : {}),
+                };
+                try {
+                    built = provider(destination, client, seed, fourth);
+                }
+                catch {
+                    throw new DestinationConfigError_1.DestinationConfigError(destination, ['provider', 'clientAuthentication'], 'the token provider factory failed beside the clientAuthentication strategy');
+                }
+            }
+            else {
+                // 4.0.0: the stored secret and refresh token carried over as read.
+                client = composeAuthorization(read, storedRefreshTokenOf(read.session));
+                binding = (0, binding_1.consumerBinding)(serviceUrl, sapClient, client);
+                carry = 'any';
+                built = provider(destination, client, {
+                    ...(connConfig ?? {}),
+                    serviceUrl,
+                });
+            }
+            this.logger.debug(`[AuthBroker] Provider built for ${destination}`, {
+                hasCredentials: !!client,
+                hasRefreshToken: !!client?.refreshToken,
+                hasStoredToken: !!(connConfig?.authorizationToken || connConfig?.sessionCookies),
+            });
+            return { provider: built, binding, carry };
         });
-        this.providers.set(destination, built);
-        this.logger.debug(`[AuthBroker] Provider built for ${destination}`, {
-            hasCredentials: !!authConfig,
-            hasRefreshToken: !!authConfig?.refreshToken,
-            hasStoredToken: !!(connConfig?.authorizationToken || connConfig?.sessionCookies),
+        this.consumerBuilt.set(destination, build);
+        build.catch(() => {
+            if (this.consumerBuilt.get(destination) === build) {
+                this.consumerBuilt.delete(destination);
+            }
         });
-        return built;
+        return build;
+    }
+    /**
+     * The token API's strategy path: with a `clientAuthentication` strategy and a
+     * destination stating a grant whose client authenticates, the strategy's
+     * answer — resolved inside the guard — and the client identity: the secret
+     * client, else the certificate client's, read through the context's memoised
+     * `readCertificate`. `null` without a strategy (4.0.0: nothing
+     * certificate-related is asked) and for a grant that authenticates no
+     * client (`saml2_pure`, `none`), as `getProvider` decides.
+     *
+     * The strategy is told the grant, so a destination that states none is
+     * refused before it is called rather than built without it. (An instance
+     * given as `provider` is the consumer's own composition: the strategy
+     * applies only to what the broker builds, so it is not used there.)
+     */
+    async consumerClientAuthentication(destination, means, client) {
+        const strategy = this.clientAuthentication;
+        if (!strategy) {
+            return null;
+        }
+        // basic and snc never get here: the token API refuses them first
+        // (`statedForTokens`).
+        if (!means || (means.authType !== 'jwt' && means.authType !== 'saml')) {
+            throw new DestinationConfigError_1.DestinationConfigError(destination, ['authType', 'grantType'], 'a clientAuthentication strategy is told the grant: the destination must state its authType and grantType');
+        }
+        const grant = (0, destinations_1.statedGrant)(destination, means.authType, means);
+        if (grant === 'saml2_pure' || grant === 'none') {
+            return null;
+        }
+        const serviceKeyStore = this.serviceKeyStore;
+        const context = (0, clientAuthentication_1.clientAuthenticationContext)(destination, grant, client, () => this.read(destination, 'client certificate', async () => serviceKeyStore?.getClientCertificate
+            ? serviceKeyStore.getClientCertificate(destination)
+            : null));
+        const clientAuthentication = await (0, clientAuthentication_1.resolveClientAuthentication)(strategy, context);
+        return { clientAuthentication, identity: await (0, clientAuthentication_1.clientIdentity)(context) };
     }
     /**
-     * The credentials the provider is built with: the session's own when it holds
-     * them, else the service key's, carrying the refresh token the session
-     * stored. The session keeps a refresh token without credentials when the
-     * credentials came from the service key, since the broker does not copy the
-     * client secret into it; `loadSession` is where such a token is read.
+     * What a consumer's factory's credentials are composed from, read in the
+     * 3.x order: the session's authorization config; only when it has none, the
+     * session and then the key store's client. A session store of auth-stores 3
+     * answers no client, so the key store's is what is found.
      */
-    async resolveAuthorizationConfig(destination) {
+    async readAuthorization(destination) {
         const sessionAuth = await this.read(destination, 'session authorization config', () => this.sessionStore.getAuthorizationConfig(destination));
         if (sessionAuth) {
-            return sessionAuth;
+            return { sessionAuth, keyAuth: null, session: null, sessionRead: false };
         }
-        const session = await this.read(destination, 'session', () => this.sessionStore.loadSession(destination));
-        const storedRefreshToken = typeof session?.refreshToken === 'string'
-            ? session.refreshToken
-            : undefined;
+        const session = await this.loadStoredSession(destination);
         const serviceKeyStore = this.serviceKeyStore;
         const keyAuth = serviceKeyStore
             ? await this.read(destination, 'service key authorization config', () => serviceKeyStore.getAuthorizationConfig(destination))
             : null;
-        if (!keyAuth) {
-            return null;
-        }
-        return {
-            ...keyAuth,
-            refreshToken: storedRefreshToken ?? keyAuth.refreshToken,
-        };
+        return { sessionAuth: null, keyAuth, session, sessionRead: true };
     }
+    /** The session the store holds for the destination, or null. */
+    loadStoredSession(destination) {
+        return this.read(destination, 'session', () => this.sessionStore.loadSession(destination));
+    }
+    /**
+     * `serviceUrl` for a consumer's provider, in the 3.x order: the session's,
+     * else the key store's, else an error before the provider is asked.
+     */
     async resolveServiceUrl(destination, connConfig) {
         let serviceUrl = connConfig?.serviceUrl;
         const serviceKeyStore = this.serviceKeyStore;
@@ -181,53 +529,6 @@ class AuthBroker {
         }
         return serviceUrl;
     }
-    /**
-     * Writes the result by its type: a SAML result is session cookies, anything
-     * else a bearer token. The refresh token is written only when the result has
-     * one, so a provider that returns none does not erase the stored one.
-     *
-     * `ITokenResult.expiresAt` has no field in `IConnectionConfig` to go to; the
-     * provider seeded with the stored token reads the expiry from the JWT itself.
-     */
-    async persist(destination, serviceUrl, connConfig, result) {
-        const isSaml = result.tokenType === 'saml';
-        await this.sessionStore.setConnectionConfig(destination, {
-            ...(connConfig ?? {}),
-            serviceUrl,
-            authorizationToken: isSaml ? undefined : result.authorizationToken,
-            sessionCookies: isSaml ? result.authorizationToken : undefined,
-            authType: isSaml ? 'saml' : 'jwt',
-        });
-        if (result.refreshToken) {
-            const sessionAuth = await this.read(destination, 'session authorization config', () => this.sessionStore.getAuthorizationConfig(destination));
-            if (sessionAuth) {
-                // The session holds its own credentials: only the refresh token changes.
-                await this.sessionStore.setAuthorizationConfig(destination, {
-                    ...sessionAuth,
-                    refreshToken: result.refreshToken,
-                });
-            }
-            else {
-                // The credentials live in the service key and stay there. The session
-                // gets the refresh token alone — never the client secret.
-                const session = await this.read(destination, 'session', () => this.sessionStore.loadSession(destination));
-                await this.sessionStore.saveSession(destination, {
-                    ...(session ?? {}),
-                    serviceUrl: session?.serviceUrl ?? serviceUrl,
-                    refreshToken: result.refreshToken,
-                });
-            }
-        }
-        this.logger.info(`[AuthBroker] Token saved for ${destination}`, {
-            tokenType: result.tokenType ?? 'jwt',
-            authType: result.authType,
-            hasRefreshToken: !!result.refreshToken,
-            expiresAt: result.expiresAt
-                ? new Date(result.expiresAt).toISOString()
-                : undefined,
-            expiresIn: result.expiresIn,
-        });
-    }
     /**
      * A store read where absence is an answer and anything else is not.
      *
@@ -252,34 +553,299 @@ class AuthBroker {
         }
     }
     /**
-     * Authorization configuration for the destination: the session's, else the
-     * service key's, else null.
+     * The destination's client: the service key store's `uaaUrl`, `uaaClientId`
+     * and `uaaClientSecret`, with the refresh token the session stores laid over
+     * them; `null` when the key store has no client. A client a session store
+     * answers is not read, nor a refresh token a key store answers.
      */
     async getAuthorizationConfig(destination) {
-        const sessionAuth = await this.read(destination, 'session authorization config', () => this.sessionStore.getAuthorizationConfig(destination));
-        if (sessionAuth) {
-            return sessionAuth;
-        }
         const serviceKeyStore = this.serviceKeyStore;
-        if (!serviceKeyStore) {
+        const client = serviceKeyStore
+            ? await this.read(destination, 'service key authorization config', () => serviceKeyStore.getAuthorizationConfig(destination))
+            : null;
+        if (!client) {
             return null;
         }
-        return this.read(destination, 'service key authorization config', () => serviceKeyStore.getAuthorizationConfig(destination));
+        const secret = await this.read(destination, 'session', () => this.sessionStore.loadSession(destination));
+        const composed = {
+            uaaUrl: client.uaaUrl,
+            uaaClientId: client.uaaClientId,
+            uaaClientSecret: client.uaaClientSecret,
+        };
+        if (secret?.refreshToken !== undefined) {
+            composed.refreshToken = secret.refreshToken;
+        }
+        return composed;
     }
     /**
-     * Connection configuration for the destination: the session's, else the
-     * service key's (which has URLs but no token), else null.
+     * The destination's connection config: the service key store's means with
+     * the session's secret (`authorizationToken`, `sessionCookies`,
+     * `expiresAt`) and its binding (`issuedFor`, `issuedBy`) laid over them; `null` when neither store holds anything.
+     * Means a session store answers are not read, nor a secret a key store
+     * answers.
      */
     async getConnectionConfig(destination) {
-        const sessionConn = await this.read(destination, 'session connection config', () => this.sessionStore.getConnectionConfig(destination));
-        if (sessionConn) {
-            return sessionConn;
+        const serviceKeyStore = this.serviceKeyStore;
+        const means = serviceKeyStore
+            ? await this.read(destination, 'service key connection config', () => serviceKeyStore.getConnectionConfig(destination))
+            : null;
+        const secret = await this.read(destination, 'session', () => this.sessionStore.loadSession(destination));
+        const composed = {};
+        for (const [field, value] of Object.entries(means ?? {})) {
+            if (!isSecretField(field) && value !== undefined) {
+                composed[field] = value;
+            }
+        }
+        for (const field of SECRET_FIELDS) {
+            const value = secret?.[field];
+            if (value !== undefined) {
+                composed[field] = value;
+            }
+        }
+        return Object.keys(composed).length > 0 ? composed : null;
+    }
+    /**
+     * The credential for the destination, ready for a connector: the provider
+     * its configuration states (`authType`, and `grantType` for `jwt` / `saml`),
+     * built from the means the service key store holds and the secret the
+     * session store holds.
+     *
+     * One provider per destination for the broker's life: concurrent first calls
+     * share one build, and a build that threw is tried again on the next call.
+     *
+     * A token provider (the UAA, OIDC and SAML grants) is seeded from the
+     * session when the stored secret is bound to this destination, and writes
+     * every token it obtains — at `prepare()`, on expiry, or in `rejected()` after
+     * a 401 — back to the session store before it answers (see `flush()`).
+     *
+     * @throws DestinationConfigError when the destination lacks what its type
+     *   needs — naming the fields or options, never a value.
+     */
+    getProvider(destination) {
+        const cached = this.built.get(destination);
+        if (cached) {
+            return cached;
         }
+        // Deferred by one tick, so the promise is in the cache before the build
+        // reads anything.
+        const build = Promise.resolve().then(() => this.build(destination));
+        this.built.set(destination, build);
+        build.catch(() => {
+            if (this.built.get(destination) === build) {
+                this.built.delete(destination);
+            }
+        });
+        return build;
+    }
+    async build(destination) {
         const serviceKeyStore = this.serviceKeyStore;
         if (!serviceKeyStore) {
-            return null;
+            throw new DestinationConfigError_1.DestinationConfigError(destination, ['serviceKeyStore'], 'getProvider reads the means from a service key store, and none was given');
+        }
+        const means = await this.read(destination, 'means', () => serviceKeyStore.getConnectionConfig(destination));
+        const authType = (0, destinations_1.statedAuthType)(destination, means);
+        // statedAuthType refuses a destination without means.
+        const stated = means;
+        let provider;
+        if (authType === 'basic') {
+            provider = (0, destinations_1.basicProvider)(destination, stated);
+        }
+        else if (authType === 'snc') {
+            provider = (0, destinations_1.sncProvider)(destination, stated, this.logger);
+        }
+        else {
+            const grant = (0, destinations_1.statedGrant)(destination, authType, stated);
+            if (grant !== 'none') {
+                // A grant that obtains a secret: the row's client (none for
+                // saml2_pure), what a secret for this destination is bound to
+                // — written with every secret, and required of a stored one
+                // before it seeds — and the stored secret when it is.
+                const secretClient = grant === 'saml2_pure'
+                    ? null
+                    : await this.read(destination, 'client', () => serviceKeyStore.getAuthorizationConfig(destination));
+                // The consumer's client authentication, resolved inside the guard
+                // before any provider exists: a strategy that throws leaves nothing
+                // built and nothing cached. Then the client identity the row and the
+                // binding take — the secret client, else the certificate client's —
+                // so the binding and the seed are chosen from it. Without a strategy
+                // nothing of this runs: 4.0.0's client, nothing certificate-related.
+                let client = secretClient;
+                let clientAuthentication;
+                if (this.clientAuthentication && grant !== 'saml2_pure') {
+                    const context = (0, clientAuthentication_1.clientAuthenticationContext)(destination, grant, secretClient, () => this.read(destination, 'client certificate', async () => serviceKeyStore.getClientCertificate
+                        ? serviceKeyStore.getClientCertificate(destination)
+                        : null));
+                    clientAuthentication = await (0, clientAuthentication_1.resolveClientAuthentication)(this.clientAuthentication, context);
+                    client = await (0, clientAuthentication_1.clientIdentity)(context);
+                }
+                const computed = (0, bindingOf_1.destinationBinding)(authType, grant, stated, client);
+                // The strategy path: a resource neither side states matches.
+                const binding = clientAuthentication
+                    ? (0, binding_1.strategyBinding)(computed)
+                    : computed;
+                const stored = grant === 'client_credentials'
+                    ? null
+                    : await this.read(destination, 'session', () => this.sessionStore.loadSession(destination));
+                const secret = this.boundOrDiscarded(destination, stored, binding);
+                // The expiry is fixed when the result arrives, not when a retry
+                // finally writes it — on a copy; the outcome of the write is recorded
+                // against the result itself, which the provider also returns to the
+                // token API.
+                const onTokens = (result) => this.writer.submit(destination, {
+                    result: { ...result, expiresAt: expiryOf(result) },
+                    original: result,
+                    binding,
+                    carry: 'bound',
+                });
+                const common = {
+                    destination,
+                    client,
+                    secret,
+                    ...(clientAuthentication ? { clientAuthentication } : {}),
+                    logger: this.logger,
+                    onTokens,
+                };
+                if ((0, destinations_1.isUaaGrant)(grant)) {
+                    provider = (0, destinations_1.uaaProvider)({
+                        ...common,
+                        grant,
+                        authorization: this.authorization,
+                    });
+                }
+                else if ((0, destinations_1.isOidcGrant)(grant)) {
+                    provider = (0, destinations_1.oidcProvider)({
+                        ...common,
+                        grant,
+                        means: stated,
+                        oidcAuthorization: this.oidcAuthorization,
+                        deviceCodePresenter: this.deviceCodePresenter,
+                    });
+                }
+                else if ((0, destinations_1.isSamlGrant)(grant)) {
+                    provider = (0, destinations_1.samlProvider)({
+                        ...common,
+                        grant,
+                        means: stated,
+                        authorization: this.authorization,
+                        samlCookies: this.samlCookies,
+                        assertionReplayStore: this.assertionReplayStore,
+                    });
+                }
+                else {
+                    // statedGrant admits only the allowed `authType` / `grantType` pairs.
+                    throw new Error(`unreachable grant ${grant}`);
+                }
+                this.logger.debug(`[AuthBroker] Provider built for ${destination}`, {
+                    authType,
+                    grant,
+                    seeded: !!secret,
+                });
+                return provider;
+            }
+            const secret = await this.read(destination, 'session', () => this.sessionStore.loadSession(destination));
+            const client = authType === 'jwt'
+                ? await this.read(destination, 'client', () => serviceKeyStore.getAuthorizationConfig(destination))
+                : null;
+            provider = (0, destinations_1.handedOverProvider)(destination, authType, secret, (0, bindingOf_1.destinationBinding)(authType, 'none', stated, client));
+        }
+        this.logger.debug(`[AuthBroker] Provider built for ${destination}`, {
+            authType,
+        });
+        return provider;
+    }
+    /**
+     * The stored secret when it is bound to this destination's resource and
+     * issuer, else `null`: the provider is then built as with no session
+     * and logs in afresh — the refresh token is not spent either. The log line
+     * names the destination only: never a URI, never a token.
+     */
+    boundOrDiscarded(destination, stored, binding) {
+        if (!stored || (0, binding_1.boundHere)(stored, binding))
+            return stored;
+        if (present(stored.authorizationToken) ||
+            present(stored.sessionCookies) ||
+            present(stored.refreshToken)) {
+            this.logger.warn(`[AuthBroker] ${destination}: secret bound to another resource, discarded`);
+        }
+        return null;
+    }
+    /**
+     * Waits for the session writes still pending — each gets one more attempt —
+     * and rejects naming the destinations whose store still refuses. Call it on
+     * shutdown to know whether every token a provider obtained is stored; the
+     * broker keeps retrying after a rejection.
+     */
+    flush() {
+        return this.writer.flush();
+    }
+    /**
+     * One write of the destination's session secret — and nothing else:
+     * `{ authorizationToken, expiresAt, refreshToken, issuedFor, issuedBy }` in
+     * one `saveSession` — or, for a `saml2_pure` result (`tokenType: 'saml'`),
+     * `{ sessionCookies, expiresAt, issuedFor, issuedBy }`: cookies are written
+     * as cookies, every other result as a token (`saml2_bearer` included). No means is ever written: not `serviceUrl`, not
+     * `authType`, not the client — they live in the key store, which the broker
+     * never writes.
+     *
+     * - `expiresAt`: fixed by `onTokens` when the result arrived — the result's
+     *   own, else the `expiresIn` it reports counted from then (the rule the
+     *   provider applies to its own cache).
+     * - `refreshToken`: the result's, else the one the session holds, read at
+     *   write time, so a result without one does not erase the stored one — for
+     *   a provider the broker built, only a stored one bound where this one is:
+     *   a refresh token obtained for another resource or from another client is
+     *   not carried into this secret. So too for a consumer's factory beside a
+     *   `clientAuthentication` strategy, seeded only with a bound session. A
+     *   consumer's provider without one was seeded with whatever the session
+     *   held, so whatever it holds is carried (4.0.0).
+     * - `issuedFor` / `issuedBy`: the binding computed when the provider was
+     *   built, each left out when the means lack its source — so the
+     *   store clears it.
+     * - A destination the key store now states as `basic` or `snc` is not
+     *   written: those obtain no session secret.
+     */
+    async writeSecret(destination, { result, binding, carry }) {
+        const serviceKeyStore = this.serviceKeyStore;
+        const means = serviceKeyStore
+            ? await this.read(destination, 'means', () => serviceKeyStore.getConnectionConfig(destination))
+            : null;
+        if (means?.authType === 'basic' || means?.authType === 'snc') {
+            this.logger.warn(`[AuthBroker] Not written: ${destination} is a ${means.authType} destination, which holds no session secret`);
+            return;
+        }
+        let secret;
+        if (result.tokenType === 'saml') {
+            // saml2_pure: the cookies are the credential, and SAML has no refresh
+            // token to carry.
+            secret = {
+                sessionCookies: result.authorizationToken,
+                expiresAt: result.expiresAt,
+            };
         }
-        return this.read(destination, 'service key connection config', () => serviceKeyStore.getConnectionConfig(destination));
+        else {
+            const stored = result.refreshToken
+                ? null
+                : await this.read(destination, 'session', () => this.sessionStore.loadSession(destination));
+            const storedRefreshToken = present(stored?.refreshToken) &&
+                (carry === 'any' || (0, binding_1.boundHere)(stored, binding))
+                ? stored.refreshToken
+                : undefined;
+            secret = {
+                authorizationToken: result.authorizationToken,
+                expiresAt: result.expiresAt,
+                refreshToken: result.refreshToken || storedRefreshToken,
+            };
+        }
+        if (binding.issuedFor !== undefined)
+            secret.issuedFor = binding.issuedFor;
+        if (binding.issuedBy !== undefined)
+            secret.issuedBy = binding.issuedBy;
+        await this.sessionStore.saveSession(destination, secret);
+        this.logger.info(`[AuthBroker] Session secret saved for ${destination}`, {
+            credential: secret.sessionCookies !== undefined ? 'cookies' : 'token',
+            hasRefreshToken: !!secret.refreshToken,
+            expiresAt: result.expiresAt,
+        });
     }
     /**
      * An `ITokenRefresher` for one destination, for injection into a connection: