@mcp-abap-adt/auth-broker 4.0.0 → 5.0.0

package/dist/AuthBroker.js

@@ -4,13 +4,20 @@
  *
  * `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.
+ * Every token provider it builds renews through the consumer's `renewal` and
+ * writes what it obtains back to the session store through auth-providers'
+ * `refreshStatePersistence` — the secret alone, through one plain queue per
+ * destination (`SessionWriter`): a failed write stays pending until the
+ * destination's next write or `flush()`, and means what the consumer's
+ * `onWriteFailure` says; `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.
+ * same provider — the row path's — or, when the consumer gives one, the
+ * consumer's provider — the consumer path's, resolved, cached and bound on its
+ * own — whose every answer it writes through the same write path.
+ *
+ * A provider is never changed: every call re-reads what its path's
+ * provider was built from and builds a new one, starting with nothing, when
+ * anything of it changed (`buildIdentity.ts`).
  *
  * 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
@@ -21,18 +28,58 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AuthBroker = void 0;
+const auth_errors_1 = require("@mcp-abap-adt/auth-errors");
 const interfaces_auth_1 = require("@mcp-abap-adt/interfaces-auth");
 const binding_1 = require("./binding");
 const bindingOf_1 = require("./bindingOf");
+const buildIdentity_1 = require("./buildIdentity");
+const clientAuthentication_1 = require("./clientAuthentication");
+const contractShape_1 = require("./contractShape");
 const DestinationConfigError_1 = require("./DestinationConfigError");
 const destinations_1 = require("./destinations");
+const quietLogger_1 = require("./quietLogger");
 const SessionWriter_1 = require("./SessionWriter");
-const noOpLogger = {
-    info: () => { },
-    error: () => { },
-    warn: () => { },
-    debug: () => { },
-};
+const DROPPED = Object.freeze({ written: false });
+/** `work`'s result or what it threw, as a frozen outcome; never rejects. */
+async function outcomeOf(work) {
+    try {
+        return Object.freeze({ ok: true, value: await work() });
+    }
+    catch (thrown) {
+        return Object.freeze({ ok: false, thrown });
+    }
+}
+/**
+ * Joins `slot` with `start`'s work and the caller's signal, and unwraps the
+ * outcome outside `join`: the value, or the very value the work threw.
+ */
+async function joined(slot, work, signal) {
+    const outcome = await slot.join((attempt) => outcomeOf(() => work(attempt)), signal);
+    if (!outcome.ok)
+        throw outcome.thrown;
+    return outcome.value;
+}
+/**
+ * One wait of one caller — on the write queue, or a store read outside a
+ * resolution — as a waiter of a slot of its own: the caller's signal
+ * releases that caller only, and the work runs on.
+ */
+function waitFor(work, signal) {
+    return joined((0, auth_errors_1.sharedAttempt)('persisting-tokens'), work, signal);
+}
+/**
+ * Rejects `aborted` when the caller's signal has aborted by now — after its
+ * last wait, before its success — through the same one implementation: a
+ * waiter that joins with an aborted signal is refused at once.
+ */
+async function stillWanted(signal) {
+    if (signal !== undefined)
+        await waitFor(async () => undefined, signal);
+}
+/** The provider a token API call is answered by, asked with the call's signal. */
+function tokenOptions(signal) {
+    return signal === undefined ? [] : [{ signal }];
+}
 /** 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 = [
@@ -43,6 +90,33 @@ const SECRET_FIELDS = [
     '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: the connection means from an allowlist
+ * (`SEED_MEANS`) and nothing else — never the session secret's own fields
+ * (`SECRET_FIELDS`), whatever the stored record says: the consumer path is
+ * never seeded. `serviceUrl` is the one resolved for the destination.
+ */
+function consumerSeed(connConfig, serviceUrl) {
+    const source = (connConfig ?? {});
+    const seed = {};
+    for (const field of SEED_MEANS) {
+        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')
@@ -52,12 +126,68 @@ function expiryOf(result) {
     }
     return undefined;
 }
+/**
+ * The refresh token a build owns, after one reported refresh token: a
+ * string written makes it owned; `null` (a discard) writes `''` and makes it
+ * none; `undefined` writes the owned one, or `''` when the build owns none.
+ */
+function ownedAfter(owned, reported) {
+    if (present(reported))
+        return { written: reported, owned: reported };
+    if (reported === null)
+        return { written: '', owned: undefined };
+    return { written: owned ?? '', owned };
+}
+/** One map per path. */
+function perPath() {
+    return { row: new Map(), consumer: new Map() };
+}
 /** 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 client the consumer path hands its factory and tells its strategy: the
+ * session's own client, else the key store's, through the same allowlist the
+ * strategy is told (`contextClient`) — with `refreshToken` as a key, never a
+ * value: no refresh token either client read carried reaches the factory.
+ */
+function consumerClient(read) {
+    const client = (0, clientAuthentication_1.contextClient)(read.sessionAuth ?? read.keyAuth);
+    return client
+        ? (0, contractShape_1.asContract)({ ...client, refreshToken: undefined })
+        : null;
+}
+/**
+ * The consumer path's identity. A factory's: everything it is handed —
+ * the client, the seed — and what its binding is made of — the row, the
+ * resource. An instance's, which is handed nothing: the destination's
+ * identity it was first used for — the row, the resource, the issuer
+ * (`uaaUrl`, `oidcIssuerUrl`) and the client id, no secret.
+ */
+function consumerIdentity(inputs, instance) {
+    const { row, serviceUrl, sapClient, client } = inputs;
+    return instance
+        ? {
+            row,
+            serviceUrl,
+            sapClient,
+            uaaUrl: client?.uaaUrl,
+            clientId: client?.uaaClientId,
+            oidcIssuerUrl: inputs.means?.oidcIssuerUrl,
+        }
+        : { row, serviceUrl, sapClient, client, seed: inputs.seed };
+}
+/**
+ * The token API's refusal of a destination whose means changed under the
+ * consumer's instance: the instance cannot be rebuilt, and the identity of
+ * the credential it holds is unknown to the broker.
+ */
+function instanceRefusal(destination) {
+    return new DestinationConfigError_1.DestinationConfigError(destination, ['provider'], 'the destination’s means changed since the provider instance was first used for it');
+}
 /** A stored string that counts as present: `''` is none. */
 function present(value) {
     return typeof value === 'string' && value !== '';
@@ -69,13 +199,28 @@ function errorCode(error) {
     }
     return undefined;
 }
-/** A result carrying a token, or the 3.x error for one that carries none. */
-function checked(destination, result) {
+/**
+ * A result carrying a token, or the failure for one that carries none:
+ * `request-failed`, `token-source`, `no-access-token` — "the token source
+ * returned no access_token", minted by auth-errors.
+ */
+function checked(result) {
     if (!result?.authorizationToken) {
-        throw new Error(`Token provider did not return authorization token for destination "${destination}"`);
+        throw new auth_errors_1.AuthProviderFailure(auth_errors_1.authError['request-failed']({
+            operation: 'token-source',
+            problem: 'no-access-token',
+        }));
     }
     return result;
 }
+/** A token write of the provider's persistence: the report's own facts. */
+function persisted(tokens) {
+    return {
+        credential: tokens.authorizationToken,
+        cookies: tokens.tokenType === 'saml',
+        expiresAt: tokens.expiresAt,
+    };
+}
 /**
  * AuthBroker manages authentication tokens for destinations
  */
@@ -84,28 +229,37 @@ class AuthBroker {
     serviceKeyStore;
     sessionStore;
     provider;
-    /** A consumer factory's providers: the promise of the build, as `built`. */
-    consumerBuilt = new Map();
+    /** Per (destination, path): the provider handed out while unchanged. */
+    resolvedRow = new Map();
+    resolvedConsumer = 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.
+     * Per (destination, path): the slot of shared resolutions — every
+     * caller of that path is a waiter of its attempt.
      */
-    built = new Map();
+    rowSlots = new Map();
+    consumerSlots = new Map();
+    /** The broker-wide slot every `flush()` caller joins. */
+    flushSlot = (0, auth_errors_1.sharedAttempt)('persisting-tokens');
+    /** Per (destination, path): the last generation a build took. */
+    generations = perPath();
+    /** Per (destination, path): the newest generation that queued a write. */
+    newestWriter = perPath();
     /**
-     * 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.
+     * The destinations whose means changed under the consumer's instance: the
+     * token API refuses them until a new broker.
      */
-    failedWrites = new WeakMap();
+    instanceRefused = new Set();
     authorization;
     oidcAuthorization;
     deviceCodePresenter;
     samlCookies;
     assertionReplayStore;
-    /** getProvider's writes of the session secret, retried on their own. */
+    clientAuthentication;
+    renewal;
+    onWriteFailure;
+    /** `config.authDebug === true`: what every token provider it builds is told. */
+    authDebug;
+    /** Every write of the session secret: one plain queue per destination. */
     writer;
     /**
      * @param config Stores and the provider (instance or factory)
@@ -158,25 +312,15 @@ class AuthBroker {
         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.clientAuthentication = config.clientAuthentication;
+        this.renewal = config.renewal;
+        this.onWriteFailure = config.onWriteFailure;
+        // Every line the broker writes, and every line of a provider it builds,
+        // goes through one guard: a consumer logger that throws or rejects
+        // changes no outcome.
+        this.logger = (0, quietLogger_1.quietLogger)(logger);
+        this.authDebug = config.authDebug === true;
+        this.writer = new SessionWriter_1.SessionWriter((destination, write) => this.writeSecret(destination, write), this.logger);
         this.logger.debug('[AuthBroker] Broker initialized', {
             hasServiceKeyStore: !!serviceKeyStore,
             providerForm: provider === undefined
@@ -192,36 +336,83 @@ class AuthBroker {
      *
      * 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,
+     * serve both — and what it obtains is written by its persistence. 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.
+     * A provider's failure is relayed as the same object; a store's read
+     * failure reaches the caller as the store raised it. A write that did not
+     * land fails the call under `onWriteFailure: 'fail'` (`unknown`,
+     * `persisting-tokens`) — the token stands, and the write stays pending: the
+     * destination's next call retries it first and is refused while it fails —
+     * and is only logged under `'continue'`.
      *
      * @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.
+     *   `basic` or `snc`, before any provider is asked; without the
+     *   `onWriteFailure` option; without a consumer `provider`, also for one
+     *   whose provider obtains no token.
      */
-    async getToken(destination) {
-        return this.obtain(destination, 'getTokens');
+    async getToken(destination, options) {
+        return this.obtain(destination, 'getTokens', options?.signal);
     }
     /**
      * 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()`;
      * a renewal already in flight for the destination is joined, not repeated.
      */
-    async refreshToken(destination) {
-        return this.obtain(destination, 'refreshTokens');
+    async refreshToken(destination, options) {
+        return this.obtain(destination, 'refreshTokens', options?.signal);
     }
-    async obtain(destination, method) {
-        const means = await this.statedForTokens(destination);
+    /**
+     * The token API's one body. The call's signal releases this caller from
+     * every wait it has — the write checks, the means read, the resolution
+     * (whose waiter it is, never attaching), its own write — and is
+     * passed to the provider's `getTokens` / `refreshTokens`.
+     */
+    async obtain(destination, method, signal) {
+        if (this.provider && !(0, destinations_1.isWriteFailurePolicy)(this.onWriteFailure)) {
+            // Every answer of the consumer's provider is written: what a failed
+            // write means is the consumer's to say. (Without one, getProvider's
+            // token row refuses the same.)
+            throw new DestinationConfigError_1.DestinationConfigError(destination, ['onWriteFailure'], 'the token API writes the session secret: say what a failed write means');
+        }
+        await this.settlePending(destination, signal);
+        // This call's reads: the means once, for the check and the resolution.
+        const reads = this.storeReads(destination);
+        const means = await waitFor(() => this.statedForTokens(destination, reads), signal);
         const result = this.provider
-            ? await this.obtainFromConsumer(destination, method, means)
-            : await this.obtainShared(destination, method, means);
+            ? await this.obtainFromConsumer(destination, method, reads, signal)
+            : await this.obtainShared(destination, method, means, reads, signal);
+        // A write queued meanwhile — a discard of the destination's provider the
+        // store rejected, say — is caught here.
+        await this.settlePending(destination, signal);
+        // A signal that aborted after the last wait: never success.
+        await stillWanted(signal);
         return result.authorizationToken;
     }
+    /**
+     * Under `onWriteFailure: 'fail'`, a call of the destination is refused while
+     * its last write is pending — not yet landed: failed, or still queued
+     * or in flight. Asked on entry and right before success: the call awaits
+     * every write of the destination queued before this moment, and a failed
+     * one that no later write replaced is written once more — the destination's
+     * next write, queued like any other. All landed: on entry the call goes on,
+     * at the end it returns its success. Still failing: it rejects (`unknown`,
+     * `persisting-tokens`). A write queued after the check is not this call's.
+     * Under `'continue'` nothing is asked.
+     *
+     * The one wait is `writer.retry(destination)`'s promise, a waiter of its
+     * own slot with the call's signal: an abort releases the caller
+     * (`aborted`), never with success, and the write runs on.
+     */
+    async settlePending(destination, signal) {
+        if (this.onWriteFailure !== 'fail')
+            return;
+        const outcome = await waitFor(() => this.writer.retry(destination), signal);
+        if (!outcome.landed) {
+            throw new auth_errors_1.AuthProviderFailure((0, auth_errors_1.classify)(outcome.error, 'persisting-tokens'));
+        }
+    }
     /**
      * 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
@@ -229,10 +420,9 @@ class AuthBroker {
      * 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))
+    async statedForTokens(destination, reads) {
+        const means = this.serviceKeyStore
+            ? (await reads.read('means'))
             : null;
         const authType = means?.authType;
         if (authType === 'basic' || authType === 'snc') {
@@ -240,8 +430,11 @@ class AuthBroker {
         }
         return means;
     }
-    /** The token API on `getProvider`'s provider. */
-    async obtainShared(destination, method, means) {
+    /**
+     * The token API on the row path's provider — the one `getProvider` hands
+     * out, resolved the same way, never through `getProvider` itself.
+     */
+    async obtainShared(destination, method, means, reads, signal) {
         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');
         }
@@ -249,129 +442,302 @@ class AuthBroker {
             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);
+        // The row path's provider, through a waiter of its slot that never
+        // attaches: a token call can neither keep a later moment's login
+        // alive nor bound it.
+        const { provider } = await this.resolveRow(destination, signal, reads);
         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 provider's failure — a write its persistence awaited included — is
+        // relayed as the same object.
+        return checked(await provider[method](...tokenOptions(signal)));
     }
     /**
-     * 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.
+     * The token API on the consumer's provider: resolved on the consumer path,
+     * every answer — a cache hit included — written, the secret alone, through
+     * the broker's one write path, with the binding fixed when the provider was
+     * taken into use.
      */
-    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, binding } = await this.consumerProviderFor(destination, serviceUrl, connConfig, means);
+    async obtainFromConsumer(destination, method, reads, signal) {
+        const { provider, binding, generation } = await this.resolveConsumer(destination, reads, signal);
         this.logger.debug(`[AuthBroker] ${method} for ${destination}`);
-        const result = checked(destination, await provider[method]());
-        await this.writer.submit(destination, {
-            result: { ...result, expiresAt: expiryOf(result) },
-            original: result,
+        const result = checked(await provider[method](...tokenOptions(signal)));
+        // The call's own write, queued whatever the caller does next, and awaited
+        // raced against its signal: an abort releases the caller
+        // (`aborted`, never success) and the write runs on.
+        const queued = this.submit('consumer', destination, generation, {
+            credential: result.authorizationToken,
+            cookies: result.tokenType === 'saml',
+            expiresAt: expiryOf(result),
+            // The result is authoritative: no refresh token in it writes `''` — the
+            // store merges, and the stored one is never carried.
+            refreshToken: present(result.refreshToken) ? result.refreshToken : '',
             binding,
-            carry: 'any',
         });
-        this.throwFailedWrite(destination, result);
+        // Handled here too: a wait refused at once (the signal already aborted)
+        // never awaits it. It does not reject — the writer never does, and its
+        // log lines go through the quiet logger — but nothing here relies on it.
+        queued.catch(() => { });
+        const outcome = await waitFor(() => queued, signal);
+        if (outcome.written && !outcome.landed && this.onWriteFailure === 'fail') {
+            throw new auth_errors_1.AuthProviderFailure((0, auth_errors_1.classify)(outcome.error, 'persisting-tokens'));
+        }
         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;
+    /**
+     * The slot of one (destination, path)'s resolutions: a caller of
+     * the path arriving while an attempt is active joins it; when every caller
+     * of an attempt has aborted, the attempt leaves the slot at once and the
+     * next caller starts afresh. A failed or aborted resolution is not kept.
+     */
+    slotOf(slots, destination) {
+        let slot = slots.get(destination);
+        if (slot === undefined) {
+            slot = (0, auth_errors_1.sharedAttempt)('token-source');
+            slots.set(destination, slot);
         }
+        return slot;
+    }
+    /** Whether a build of this path was ever committed for the destination. */
+    everBuilt(path, destination) {
+        return this.generations[path].has(destination);
+    }
+    /** A committed build's generation, from its path's counter. */
+    nextGeneration(path, destination) {
+        const generation = (this.generations[path].get(destination) ?? 0) + 1;
+        this.generations[path].set(destination, generation);
+        return generation;
     }
     /**
-     * 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.
+     * Queues one write of a build of `path`. A write of a build older than the
+     * newest build of the same path that has queued a write for the destination
+     * is dropped — never written, never pending; a build of the other
+     * path never retires this one. A dropped write is not a failed one: the
+     * retired provider's holder keeps it, and the destination's session
+     * is the newer build's.
      */
-    consumerProviderFor(destination, serviceUrl, connConfig, means) {
-        const cached = this.consumerBuilt.get(destination);
-        if (cached) {
-            return cached;
+    async submit(path, destination, generation, write) {
+        const newest = this.newestWriter[path].get(destination) ?? 0;
+        if (generation < newest) {
+            this.logger.debug(`[AuthBroker] A replaced provider's session write for ${destination} dropped`);
+            return DROPPED;
         }
-        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),
-                };
+        this.newestWriter[path].set(destination, generation);
+        return Object.freeze({
+            written: true,
+            ...(await this.writer.submit(destination, write)),
+        });
+    }
+    /** This call's store reads: each source read at most once. */
+    storeReads(destination) {
+        return new buildIdentity_1.StoreReads((name) => {
+            const serviceKeyStore = this.serviceKeyStore;
+            switch (name) {
+                case 'means':
+                    return serviceKeyStore
+                        ? this.read(destination, 'means', () => serviceKeyStore.getConnectionConfig(destination))
+                        : Promise.resolve(null);
+                case 'client':
+                    return serviceKeyStore
+                        ? this.read(destination, 'client', () => serviceKeyStore.getAuthorizationConfig(destination))
+                        : Promise.resolve(null);
+                case 'certificate':
+                    return this.read(destination, 'client certificate', async () => serviceKeyStore?.getClientCertificate
+                        ? serviceKeyStore.getClientCertificate(destination)
+                        : null);
+                case 'sessionConnection':
+                    return this.read(destination, 'session connection config', () => this.sessionStore.getConnectionConfig(destination));
+                case 'sessionClient':
+                    return this.read(destination, 'session authorization config', () => this.sessionStore.getAuthorizationConfig(destination));
             }
-            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),
+        }, (field) => new DestinationConfigError_1.DestinationConfigError(destination, [field], `the store answered ${field} in a shape the broker cannot take`));
+    }
+    /**
+     * The consumer path's provider for the destination: the cached one
+     * while everything it was built from is unchanged; else, for a factory, a
+     * new build — the factory called again, its provider starting with nothing
+     * — and, for an instance, which cannot be rebuilt, a refusal naming
+     * `provider` until a new broker.
+     */
+    resolveConsumer(destination, reads, signal) {
+        const slot = this.slotOf(this.consumerSlots, destination);
+        return joined(slot, async (attempt) => {
+            const instance = typeof this.provider !== 'function';
+            if (this.instanceRefused.has(destination)) {
+                throw instanceRefusal(destination);
+            }
+            const cached = this.resolvedConsumer.get(destination);
+            if (cached) {
+                if (await cached.identity.unchanged(reads))
+                    return cached;
+                // A doomed attempt changes nothing: every caller left while
+                // it re-read, and a fresh attempt may have committed meanwhile —
+                // the entry is no longer this attempt's to remove. A live attempt
+                // is the slot's only one, so the entry is still the one it read.
+                if (attempt.signal.aborted)
+                    throw attempt.signal.reason;
+                this.resolvedConsumer.delete(destination);
+                if (instance) {
+                    this.instanceRefused.add(destination);
+                    throw instanceRefusal(destination);
+                }
+            }
+            const recorder = new buildIdentity_1.IdentityRecorder(reads);
+            const built = await this.buildConsumer(destination, recorder, attempt.signal);
+            // The commit, one step, only if the attempt was not aborted: a build
+            // every caller left is never cached nor handed out.
+            if (attempt.signal.aborted)
+                throw attempt.signal.reason;
+            const resolved = Object.freeze({
+                ...built,
+                identity: recorder.seal(),
+                generation: this.nextGeneration('consumer', destination),
             });
+            this.resolvedConsumer.set(destination, resolved);
+            return resolved;
+        }, signal);
+    }
+    /**
+     * Takes the consumer's provider into use for the destination: a factory's
+     * build — handed the means and the client, never a stored secret — or an
+     * instance as given, handed nothing. The binding is fixed here, from the
+     * `serviceUrl` (the session's, else the key store's), the SAP client and
+     * the client of this build. Every store answer is read through `recorder`:
+     * what it read is the build's identity.
+     */
+    async buildConsumer(destination, recorder, signal) {
+        const provider = this.provider;
+        const instance = typeof provider !== 'function';
+        // The identity is what this path takes from its stores — never what else
+        // the session store holds, which this broker's own writes change.
+        const inputs = await this.consumerInputs(destination, recorder.reads);
+        recorder.derived(consumerIdentity(inputs, instance), async (reads) => consumerIdentity(await this.consumerInputs(destination, reads), instance));
+        const { means, serviceUrl, sapClient, row, client, seed } = inputs;
+        if (typeof provider !== 'function') {
             return {
-                provider: built,
-                binding: (0, binding_1.consumerBinding)(serviceUrl, sapClient, client),
+                provider,
+                binding: (0, binding_1.consumerBinding)(row, serviceUrl, sapClient, null),
             };
-        });
-        this.consumerBuilt.set(destination, build);
-        build.catch(() => {
-            if (this.consumerBuilt.get(destination) === build) {
-                this.consumerBuilt.delete(destination);
+        }
+        // Never seeded: the factory is handed the means and the client
+        // only — no stored token, cookies, expiry or refresh token, in any
+        // argument, whatever the stored session's record says. The broker
+        // cannot know what the factory composes from what it is handed.
+        const strategic = await this.consumerClientAuthentication(destination, means, client, recorder, signal);
+        let built;
+        let binding;
+        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 binding is only
+            // ever written, never compared: this path seeds from nothing.
+            binding = (0, binding_1.consumerBinding)(row, serviceUrl, sapClient, strategic.identity);
+            const fourth = {
+                clientAuthentication: strategic.clientAuthentication,
+                ...(strategic.identity
+                    ? {
+                        uaaUrl: strategic.identity.uaaUrl,
+                        clientId: strategic.identity.uaaClientId,
+                    }
+                    : {}),
+            };
+            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 {
+            binding = (0, binding_1.consumerBinding)(row, serviceUrl, sapClient, client);
+            built = provider(destination, client, seed);
+        }
+        this.logger.debug(`[AuthBroker] Provider built for ${destination}`, {
+            hasCredentials: !!client,
         });
-        return build;
+        return { provider: built, binding };
+    }
+    /**
+     * 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, recorder, signal) {
+        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 context = (0, clientAuthentication_1.clientAuthenticationContext)(destination, grant, client, () => recorder.read('certificate'), signal);
+        const clientAuthentication = await (0, clientAuthentication_1.resolveClientAuthentication)(strategy, context);
+        return { clientAuthentication, identity: await (0, clientAuthentication_1.clientIdentity)(context) };
     }
     /**
-     * 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
+     * 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
+     * key store's client. The stored session is not read: nothing of it is
+     * handed to the factory. 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));
+    async readAuthorization(reads) {
+        const sessionAuth = (await reads.read('sessionClient'));
         if (sessionAuth) {
-            return sessionAuth;
+            return { sessionAuth, keyAuth: null };
         }
-        const session = await this.read(destination, 'session', () => this.sessionStore.loadSession(destination));
-        const storedRefreshToken = typeof session?.refreshToken === 'string'
-            ? session.refreshToken
-            : undefined;
-        const serviceKeyStore = this.serviceKeyStore;
-        const keyAuth = serviceKeyStore
-            ? await this.read(destination, 'service key authorization config', () => serviceKeyStore.getAuthorizationConfig(destination))
+        const keyAuth = this.serviceKeyStore
+            ? (await reads.read('client'))
             : null;
-        if (!keyAuth) {
-            return null;
-        }
+        return { sessionAuth: null, keyAuth };
+    }
+    /**
+     * What the consumer path takes from its stores for one destination, read
+     * from `reads` — the same function for a build and for every later call's
+     * comparison: the means, the `serviceUrl` (the session's, else the key
+     * store's), the SAP client, the row, the client through its allowlist, and
+     * the factory's seed of allowlisted connection means.
+     */
+    async consumerInputs(destination, reads) {
+        const means = this.serviceKeyStore
+            ? (await reads.read('means'))
+            : null;
+        const connConfig = (await reads.read('sessionConnection'));
+        const serviceUrl = this.serviceUrlOf(destination, connConfig, means);
         return {
-            ...keyAuth,
-            refreshToken: storedRefreshToken ?? keyAuth.refreshToken,
+            means,
+            serviceUrl,
+            sapClient: present(connConfig?.sapClient)
+                ? connConfig.sapClient
+                : means?.sapClient,
+            row: (0, bindingOf_1.consumerRow)(means),
+            client: consumerClient(await this.readAuthorization(reads)),
+            seed: consumerSeed(connConfig, serviceUrl),
         };
     }
     /**
      * `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;
-        if (!serviceUrl && serviceKeyStore) {
-            const keyConn = await this.read(destination, 'service key connection config', () => serviceKeyStore.getConnectionConfig(destination));
-            serviceUrl = keyConn?.serviceUrl;
-        }
+    serviceUrlOf(destination, connConfig, means) {
+        const serviceUrl = connConfig?.serviceUrl || means?.serviceUrl;
         if (!serviceUrl) {
             throw new Error(`Session for destination "${destination}" is missing required field 'serviceUrl'. ` +
                 `SessionStore must contain initial session with serviceUrl${this.serviceKeyStore ? ' or serviceKeyStore must contain serviceUrl' : ''}.`);
@@ -459,39 +825,108 @@ class AuthBroker {
      * 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 provider is never changed: every call re-reads what the
+     * destination's provider was built from — the means, the client, and the
+     * certificate client when the build read it — and answers the cached
+     * provider while all of it is unchanged. When anything changed, by a single
+     * character, it builds a new provider, which starts with nothing — no token,
+     * no refresh token, nothing of the old provider or of a session written
+     * under other means — and never hands the old one out again; whoever holds
+     * it keeps it, and its writes are dropped once the new one has written.
+     * Concurrent calls share one resolution; a resolution 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()`).
+     * session only at its destination's first build in this broker, and only
+     * when the stored secret is bound to exactly this build's means (fully
+     * stated); it 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()`).
+     *
+     * `options.signal` releases this caller from every wait (`aborted`), and is
+     * attached to the token or SNC provider answered — built or cached — so a
+     * login it starts later is aborted once every session holding it has gone
+     *. Without a signal nothing is attached.
      *
      * @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);
+    async getProvider(destination, options) {
+        const signal = options?.signal;
+        await this.settlePending(destination, signal);
+        const { provider, parties } = await this.resolveRow(destination, signal);
+        await this.settlePending(destination, signal);
+        // A signal that aborted after the last wait: never success.
+        await stillWanted(signal);
+        // Attached after the resolution, to the provider answered — built or
+        // from the cache — so a login it starts later in a moment is aborted once
+        // every session holding it has gone. Nothing kept to detach: a
+        // session ends by aborting its signal.
+        if (signal !== undefined)
+            parties?.attach(signal);
+        return provider;
+    }
+    /**
+     * The row path's provider for the destination: the cached one while what
+     * its build read is unchanged, else a new build, committed with the
+     * next generation of the row path.
+     */
+    resolveRow(destination, signal, reads = this.storeReads(destination)) {
+        const slot = this.slotOf(this.rowSlots, destination);
+        return joined(slot, async (attempt) => {
+            const cached = this.resolvedRow.get(destination);
+            if (cached) {
+                if (await cached.identity.unchanged(reads))
+                    return cached;
+                // A doomed attempt changes nothing: every caller left while
+                // it re-read, and a fresh attempt may have committed meanwhile —
+                // the entry is no longer this attempt's to remove. A live attempt
+                // is the slot's only one, so the entry is still the one it read.
+                if (attempt.signal.aborted)
+                    throw attempt.signal.reason;
+                // Changed: never handed out again.
+                this.resolvedRow.delete(destination);
             }
-        });
-        return build;
+            const recorder = new buildIdentity_1.IdentityRecorder(reads);
+            const commit = { generation: 0 };
+            const { provider, parties } = await this.build(destination, recorder, {
+                // Only a first build may start from the store; a replacement starts
+                // with nothing.
+                seeded: !this.everBuilt('row', destination),
+                commit,
+                signal: attempt.signal,
+            });
+            // The commit — the cache set, the generation taken — is one step that
+            // runs only if the attempt was not aborted: a build every caller left
+            // is never cached, never handed out, and, never asked for a token,
+            // writes nothing.
+            if (attempt.signal.aborted)
+                throw attempt.signal.reason;
+            commit.generation = this.nextGeneration('row', destination);
+            const resolved = Object.freeze({
+                provider,
+                parties,
+                identity: recorder.seal(),
+                generation: commit.generation,
+            });
+            this.resolvedRow.set(destination, resolved);
+            return resolved;
+        }, signal);
     }
-    async build(destination) {
+    /**
+     * One build of the destination's row. Every store answer it reads goes
+     * through `recorder` — what it read is its identity. `seeded`: whether the
+     * build may start from the stored session; `commit`: the generation its
+     * writes carry, set when the build is committed; `signal`: the build's
+     * attempt, handed to the `clientAuthentication` strategy. Answers
+     * the provider and the row it stated.
+     */
+    async build(destination, recorder, { seeded, commit, signal, }) {
         const serviceKeyStore = this.serviceKeyStore;
         if (!serviceKeyStore) {
             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 means = await recorder.read('means');
         const authType = (0, destinations_1.statedAuthType)(destination, means);
         // statedAuthType refuses a destination without means.
         const stated = means;
@@ -500,7 +935,11 @@ class AuthBroker {
             provider = (0, destinations_1.basicProvider)(destination, stated);
         }
         else if (authType === 'snc') {
-            provider = (0, destinations_1.sncProvider)(destination, stated, this.logger);
+            const snc = (0, destinations_1.sncProvider)(destination, stated, this.logger);
+            this.logger.debug(`[AuthBroker] Provider built for ${destination}`, {
+                authType,
+            });
+            return { provider: snc, parties: snc };
         }
         else {
             const grant = (0, destinations_1.statedGrant)(destination, authType, stated);
@@ -509,40 +948,100 @@ class AuthBroker {
                 // 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'
+                const secretClient = 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'
+                    : await recorder.read('client');
+                // The consumer's renewal and write policy have no default: a row
+                // without either is refused — with everything else it lacks, in one
+                // error — before any collaborator, the clientAuthentication strategy
+                // included, is called.
+                if ((0, destinations_1.optionsLacking)({
+                    renewal: this.renewal,
+                    onWriteFailure: this.onWriteFailure,
+                }).length > 0) {
+                    throw this.rowRefusal(destination, grant, stated, secretClient);
+                }
+                // 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;
+                // The certificate client, when the build read it: its certUrl and
+                // public certificate go into the binding (never its key).
+                let certificateRead;
+                if (this.clientAuthentication && grant !== 'saml2_pure') {
+                    const context = (0, clientAuthentication_1.clientAuthenticationContext)(destination, grant, secretClient, () => {
+                        certificateRead =
+                            recorder.read('certificate');
+                        return certificateRead;
+                    }, signal);
+                    clientAuthentication = await (0, clientAuthentication_1.resolveClientAuthentication)(this.clientAuthentication, context);
+                    client = await (0, clientAuthentication_1.clientIdentity)(context);
+                }
+                // A read that failed — and that a consumer's strategy caught — read
+                // no certificate client.
+                const certificate = certificateRead
+                    ? await certificateRead.catch(() => null)
+                    : null;
+                // Its certificate is hashed into the binding: one that is no PEM
+                // string is refused, never hashed as if the build had read none.
+                if (certificate && !present(certificate.certificate)) {
+                    throw new DestinationConfigError_1.DestinationConfigError(destination, ['clientAuthentication'], 'the client certificate the key store answered holds no certificate');
+                }
+                const computed = (0, bindingOf_1.destinationBinding)(authType, grant, stated, client, certificate);
+                // The strategy path: a resource neither side states matches.
+                const binding = clientAuthentication
+                    ? (0, binding_1.strategyBinding)(computed)
+                    : computed;
+                // Only a first build reads the session: a replacement for changed
+                // means starts with nothing. client_credentials takes no seed.
+                const stored = grant === 'client_credentials' || !seeded
                     ? 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',
-                });
+                // The refresh token this build owns: the one the builder handed its
+                // provider from the checked session (`RowBuild`), then whatever each
+                // of its writes made of it — never one read from the store at write
+                // time. Set before the provider can write.
+                let owned;
+                // The provider's persistence writes through here: resolved when the
+                // write landed, rejected with the store's error when it did not —
+                // refreshStatePersistence then does what onWriteFailure says.
+                const write = async (tokens) => {
+                    const next = ownedAfter(owned, tokens.refreshToken);
+                    owned = next.owned;
+                    const outcome = await this.submit('row', destination, commit.generation, {
+                        ...persisted(tokens),
+                        refreshToken: next.written,
+                        binding,
+                    });
+                    if (outcome.written && !outcome.landed)
+                        throw outcome.error;
+                };
                 const common = {
                     destination,
                     client,
                     secret,
+                    ...(clientAuthentication ? { clientAuthentication } : {}),
+                    renewal: this.renewal,
+                    onWriteFailure: this.onWriteFailure,
+                    write,
                     logger: this.logger,
-                    onTokens,
+                    authDebug: this.authDebug,
                 };
+                let built;
                 if ((0, destinations_1.isUaaGrant)(grant)) {
-                    provider = (0, destinations_1.uaaProvider)({
+                    built = (0, destinations_1.uaaProvider)({
                         ...common,
                         grant,
                         authorization: this.authorization,
                     });
                 }
                 else if ((0, destinations_1.isOidcGrant)(grant)) {
-                    provider = (0, destinations_1.oidcProvider)({
+                    built = (0, destinations_1.oidcProvider)({
                         ...common,
                         grant,
                         means: stated,
@@ -551,7 +1050,7 @@ class AuthBroker {
                     });
                 }
                 else if ((0, destinations_1.isSamlGrant)(grant)) {
-                    provider = (0, destinations_1.samlProvider)({
+                    built = (0, destinations_1.samlProvider)({
                         ...common,
                         grant,
                         means: stated,
@@ -564,29 +1063,77 @@ class AuthBroker {
                     // statedGrant admits only the allowed `authType` / `grantType` pairs.
                     throw new Error(`unreachable grant ${grant}`);
                 }
+                owned = built.seededRefreshToken;
+                const tokenProvider = built.provider;
                 this.logger.debug(`[AuthBroker] Provider built for ${destination}`, {
                     authType,
                     grant,
                     seeded: !!secret,
                 });
-                return provider;
+                return { provider: tokenProvider, parties: tokenProvider };
             }
             const secret = await this.read(destination, 'session', () => this.sessionStore.loadSession(destination));
             const client = authType === 'jwt'
-                ? await this.read(destination, 'client', () => serviceKeyStore.getAuthorizationConfig(destination))
+                ? await recorder.read('client')
                 : 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;
+        return { provider, parties: undefined };
+    }
+    /**
+     * A token row's refusal when the consumer's `renewal` or `onWriteFailure`
+     * is missing — named beside every other field and option the row lacks, in
+     * one error — decided before any collaborator is called. With a
+     * clientAuthentication strategy and no secret client, the client's fields
+     * are not judged: the strategy would tell the certificate client's.
+     */
+    rowRefusal(destination, grant, means, secretClient) {
+        const clientAuthenticated = !!this.clientAuthentication && grant !== 'saml2_pure';
+        const client = clientAuthenticated && !secretClient ? undefined : secretClient;
+        const check = {
+            destination,
+            client,
+            clientAuthenticated,
+            renewal: this.renewal,
+            onWriteFailure: this.onWriteFailure,
+        };
+        const refusal = (0, destinations_1.isUaaGrant)(grant)
+            ? (0, destinations_1.uaaRefusal)({ ...check, grant, authorization: this.authorization })
+            : (0, destinations_1.isOidcGrant)(grant)
+                ? (0, destinations_1.oidcRefusal)({
+                    ...check,
+                    grant,
+                    means,
+                    oidcAuthorization: this.oidcAuthorization,
+                    deviceCodePresenter: this.deviceCodePresenter,
+                })
+                : (0, destinations_1.samlRefusal)({
+                    ...check,
+                    grant,
+                    means,
+                    authorization: this.authorization,
+                    samlCookies: this.samlCookies,
+                    assertionReplayStore: this.assertionReplayStore,
+                });
+        return (refusal ??
+            new DestinationConfigError_1.DestinationConfigError(destination, (0, destinations_1.optionsLacking)(check), `a destination with grantType ${grant} lacks what its grant needs`));
     }
     /**
      * 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.
+     * and logs in afresh — the refresh token is not spent either.
+     *
+     * A stored credential not taken is logged in fixed words naming the
+     * destination only — never a URI, a record or a token: a `warn` when the
+     * binding could ever be seeded (`couldBeSeeded`) — the stored secret is not
+     * recorded under the current means: another resource, row, client,
+     * endpoint or trust, a 4.x record, or none — and a `debug` line when it
+     * never could — a row never seeded by design (`token_exchange`), means
+     * lacking what the record needs, or no `serviceUrl` — since that holds on
+     * every start and nothing was discarded by a change.
      */
     boundOrDiscarded(destination, stored, binding) {
         if (!stored || (0, binding_1.boundHere)(stored, binding))
@@ -594,44 +1141,55 @@ class AuthBroker {
         if (present(stored.authorizationToken) ||
             present(stored.sessionCookies) ||
             present(stored.refreshToken)) {
-            this.logger.warn(`[AuthBroker] ${destination}: secret bound to another resource, discarded`);
+            if ((0, binding_1.couldBeSeeded)(binding)) {
+                this.logger.warn(`[AuthBroker] ${destination}: the stored session secret is not recorded as issued under the destination's current means; not used, the provider obtains a new one`);
+            }
+            else {
+                this.logger.debug(`[AuthBroker] ${destination}: the destination's means do not state everything a session secret is bound to; a stored one is never used`);
+            }
         }
         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.
+     * Waits for every session write queued so far and gives each pending one —
+     * a write that did not land — one more attempt; rejects naming the
+     * destinations whose store still refuses (an `AggregateError` of
+     * `SessionWriteFailure`s). Nothing retries a pending write on its own: only
+     * the destination's next write or `flush()` does, so call it on shutdown to
+     * know whether every token a provider obtained is stored.
+     *
+     * Every caller joins one broker-wide slot: its signal releases that
+     * caller alone (`aborted`); the attempts run on, and a write still failing
+     * stays pending. The `AggregateError` is rethrown as the same object to
+     * every caller.
      */
-    flush() {
-        return this.writer.flush();
+    flush(options) {
+        return joined(this.flushSlot, () => this.writer.flush(), options?.signal);
     }
     /**
-     * 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.
+     * One write of the destination's session secret — and nothing else — in one
+     * `saveSession`, built from the write alone: the store merges, so every
+     * field that must not survive from an earlier write is stated.
      *
-     * - `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 credential: `{ authorizationToken, expiresAt, refreshToken, issuedFor,
+     *   issuedBy }`, or for `saml2_pure`'s cookies (`tokenType: 'saml'`)
+     *   `{ sessionCookies, expiresAt, refreshToken: '', issuedFor, issuedBy }` —
+     *   SAML has no refresh token, and one stored beside earlier cookies or a
+     *   token is not this credential's.
+     * - `refreshToken`: decided when the write was submitted — the build's own,
+     *   or `''`, the store's clearing operation. The store is never read here.
+     * - `issuedFor` / `issuedBy`: the binding fixed when the provider was built,
+     *   `issuedFor` written as `''` when the means lack its source — never left
+     *   out, so no earlier binding survives beside a new credential.
+     * - A write that holds no credential (a refresh token discarded before any
+     *   was held) writes only `refreshToken: ''`: the stored credential keeps
+     *   its own binding — never re-labelled — and loses its refresh token.
+     * - `expiresAt`: fixed when the credential arrived.
      * - 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 }) {
+    async writeSecret(destination, write) {
+        const { binding } = write;
         const serviceKeyStore = this.serviceKeyStore;
         const means = serviceKeyStore
             ? await this.read(destination, 'means', () => serviceKeyStore.getConnectionConfig(destination))
@@ -640,49 +1198,39 @@ class AuthBroker {
             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 (write.credential === '') {
+            await this.sessionStore.saveSession(destination, (0, contractShape_1.asContract)({ refreshToken: '' }));
+            this.logger.info(`[AuthBroker] Refresh token cleared for ${destination}`);
+            return;
         }
-        if (binding.issuedFor !== undefined)
-            secret.issuedFor = binding.issuedFor;
-        if (binding.issuedBy !== undefined)
-            secret.issuedBy = binding.issuedBy;
+        const secret = (0, contractShape_1.asContract)({
+            ...(write.cookies
+                ? { sessionCookies: write.credential }
+                : { authorizationToken: write.credential }),
+            expiresAt: write.expiresAt,
+            // saml2_pure: the cookies are the credential, and SAML has none.
+            refreshToken: write.cookies ? '' : write.refreshToken,
+            issuedFor: binding.issuedFor ?? '',
+            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,
+            credential: write.cookies ? 'cookies' : 'token',
+            hasRefreshToken: present(secret.refreshToken),
+            expiresAt: write.expiresAt,
         });
     }
     /**
      * An `ITokenRefresher` for one destination, for injection into a connection:
      * `getToken()` is the broker's `getToken`, `refreshToken()` its forced
-     * `refreshToken`.
+     * `refreshToken` — each call a waiter with `options.signal`, so a
+     * refresher held by a session ends with it.
      */
-    createTokenRefresher(destination) {
+    createTokenRefresher(destination, options) {
+        const signal = options?.signal;
         return {
-            getToken: () => this.getToken(destination),
-            refreshToken: () => this.refreshToken(destination),
+            getToken: () => this.getToken(destination, { signal }),
+            refreshToken: () => this.refreshToken(destination, { signal }),
         };
     }
 }