@mcp-abap-adt/auth-broker 3.0.4 → 4.0.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,46 @@
 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 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);
+/** 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');
+}
+/** 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 +69,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 +84,29 @@ 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;
+    /** 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 +119,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 +131,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,69 +153,192 @@ 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.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 } = 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}"`);
-        }
-        await this.persist(destination, serviceUrl, connConfig, result);
-        return result.authorizationToken;
+        const result = checked(destination, await provider[method]());
+        await this.writer.submit(destination, {
+            result: { ...result, expiresAt: expiryOf(result) },
+            original: result,
+            binding,
+            carry: 'any',
+        });
+        this.throwFailedWrite(destination, result);
+        return result;
     }
-    async providerFor(destination, serviceUrl, connConfig) {
-        if (typeof this.provider !== 'function') {
-            return this.provider;
+    /** 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;
         }
-        const existing = this.providers.get(destination);
-        if (existing) {
-            return existing;
+    }
+    /**
+     * 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 authConfig = await this.resolveAuthorizationConfig(destination);
-        const built = this.provider(destination, authConfig, {
-            ...(connConfig ?? {}),
-            serviceUrl,
+        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),
+                };
+            }
+            const client = await this.resolveAuthorizationConfig(destination);
+            const 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: (0, binding_1.consumerBinding)(serviceUrl, sapClient, client),
+            };
         });
-        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 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.
+     * The credentials a consumer's factory is built with: the session's own when
+     * it holds them, else the service key's, carrying the refresh token the
+     * session stored — the 3.x order. A session store of auth-stores 3
+     * answers no client, so the key store's is what is found.
      */
     async resolveAuthorizationConfig(destination) {
         const sessionAuth = await this.read(destination, 'session authorization config', () => this.sessionStore.getAuthorizationConfig(destination));
@@ -168,6 +361,10 @@ class AuthBroker {
             refreshToken: storedRefreshToken ?? keyAuth.refreshToken,
         };
     }
+    /**
+     * `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 +378,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 +402,277 @@ 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);
         }
-        return this.read(destination, 'service key connection config', () => serviceKeyStore.getConnectionConfig(destination));
+        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 client = grant === 'saml2_pure'
+                    ? null
+                    : await this.read(destination, 'client', () => serviceKeyStore.getAuthorizationConfig(destination));
+                const binding = (0, bindingOf_1.destinationBinding)(authType, grant, stated, client);
+                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,
+                    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. A consumer's provider was seeded
+     *   with whatever the session held, so whatever it holds is carried.
+     * - `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,
+            };
+        }
+        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: