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

package/dist/AuthBroker.d.ts

@@ -3,13 +3,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
@@ -19,22 +26,72 @@
  * broker does not repeat or override any of them.
  */
 import type { IDeviceCodePresenter, OidcCallbackResult } from '@mcp-abap-adt/auth-providers';
-import type { IAssertionReplayStore, IAuthorizationStrategy, IAuthProvider, IRefreshableTokenProvider, ITokenRefresher } from '@mcp-abap-adt/interfaces-auth';
+import type { IAssertionReplayStore, IAuthorizationStrategy, IAuthProvider, IClientAuthentication, IRefreshableTokenProvider, ITokenRefresher } from '@mcp-abap-adt/interfaces-auth';
 import type { ILogger } from '@mcp-abap-adt/interfaces-utils';
+import { type ClientAuthenticationStrategy } from './clientAuthentication';
+import { type RenewalOption } from './destinations';
 import type { IAuthorizationConfig, IConnectionConfig, IServiceKeyStore, ISessionStore } from './stores/interfaces';
+/** What a caller of `getProvider`, the token API and `flush()` may pass. */
+export interface BrokerCallOptions {
+    /**
+     * This caller no longer needs the answer: an abort releases this caller
+     * alone, with auth-errors' `aborted` failure (`interactive-login`), while
+     * the work it waited on runs on for the others. No bound of the broker's
+     * own: a caller that wants one passes `AbortSignal.timeout(ms)`.
+     */
+    readonly signal?: AbortSignal | undefined;
+}
 /**
- * Builds the provider for one destination, from what the stores hold for it.
+ * Builds the token API's provider for one destination, from the means and the
+ * client — never from a stored secret: the consumer path is never seeded
+ *. A consumer whose provider must resume after a restart composes that
+ * itself: its provider's own seed and persistence.
  *
- * - `authConfig`: the UAA credentials — from the session when it holds them,
- *   else from the service key — with the refresh token the session stored, or
- *   `null` when neither store has credentials (a SAML flow needs none).
- * - `connConfig`: the session's connection config, with `serviceUrl` resolved
- *   and the last token the session stored, so the provider can reuse it while
- *   it is valid.
+ * It is handed exactly these, and nothing else a store answered:
  *
- * Called once per destination; the broker keeps the provider it returns.
+ * - `authConfig`: the client, through an allowlist — `uaaUrl`, `uaaClientId`,
+ *   `uaaClientSecret` — from the session store when it answers one, else from
+ *   the key store; `refreshToken` is a key, never a value. `null` when
+ *   neither store has a client (a SAML flow needs none).
+ * - `connConfig`: the connection means, through an allowlist — `serviceUrl`
+ *   (resolved: the session's, else the key store's), and, as the session
+ *   store's connection config states them, `sapClient`, `language`,
+ *   `authType` and `grantType`. No token, cookies, expiry, refresh token or
+ *   binding, nor any other field.
+ * - `client` (`TokenProviderClient`), only beside a `clientAuthentication`
+ *   strategy, for a destination whose grant authenticates a client: the
+ *   strategy's answer and the client identity (`uaaUrl`, `clientId`); never
+ *   PEM, never a secret, never a refresh token. Without a strategy the
+ *   factory gets three arguments, as 4.0.0.
+ *
+ * Called once per build: the broker keeps the provider it returns while what
+ * it was handed is unchanged, re-reading it on every token API call;
+ * when any of it changes, the factory is called again and the new provider
+ * starts with nothing.
+ */
+export type TokenProviderFactory = (destination: string, authConfig: IAuthorizationConfig | null, connConfig: IConnectionConfig, client?: TokenProviderClient) => IRefreshableTokenProvider;
+/**
+ * The token API factory's fourth argument — present only when the broker was
+ * given a `clientAuthentication` strategy and the destination states a grant
+ * whose client authenticates; without one the factory is called with three
+ * arguments, as 4.0.0. It never carries a certificate, a key or a secret.
  */
-export type TokenProviderFactory = (destination: string, authConfig: IAuthorizationConfig | null, connConfig: IConnectionConfig) => IRefreshableTokenProvider;
+export interface TokenProviderClient {
+    /** The strategy's answer, resolved before the factory is called. */
+    readonly clientAuthentication?: IClientAuthentication;
+    /**
+     * The client's identity — the secret client's `uaaUrl` when the stores hold
+     * one, else the certificate client's; absent when there is neither.
+     */
+    readonly uaaUrl?: string;
+    /** The client id beside `uaaUrl`, from the same client. */
+    readonly clientId?: string;
+    /**
+     * Never set — not even as a key: the consumer path is handed no stored
+     * secret. Kept in the type, which 5.0.0 leaves unchanged.
+     */
+    readonly refreshToken?: string;
+}
 /** The grants whose provider takes an `IAuthorizationStrategy<string>`. */
 export type StrategyGrant = 'authorization_code' | 'passcode' | 'saml2_pure' | 'saml2_bearer';
 /**
@@ -51,26 +108,82 @@ export interface AuthBrokerConfig {
      * basic's user and password, the SNC fields, `serviceUrl`. `getProvider`
      * needs it: there is no other source of means.
      */
-    serviceKeyStore?: IServiceKeyStore;
+    serviceKeyStore?: IServiceKeyStore | undefined;
     /**
      * The token API's source: the token provider, or a factory building one per
      * destination. Not used by `getProvider`, which builds what the destination
      * states.
      *
-     * An instance is used as given, for every destination. A factory is seeded
-     * with what the stores hold for the destination (see `TokenProviderFactory`).
+     * An instance is used as given, for every destination. A factory is handed
+     * the destination's means and client, never a stored secret (see
+     * `TokenProviderFactory`).
      */
-    provider?: IRefreshableTokenProvider | TokenProviderFactory;
+    provider?: IRefreshableTokenProvider | TokenProviderFactory | undefined;
     /** The interactive strategy of the UAA code, passcode and SAML grants. */
-    authorization?: (destination: string, grant: StrategyGrant) => IAuthorizationStrategy<string>;
+    authorization?: ((destination: string, grant: StrategyGrant) => IAuthorizationStrategy<string>) | undefined;
     /** The interactive strategy of the OIDC authorization code grant. */
-    oidcAuthorization?: (destination: string) => IAuthorizationStrategy<OidcCallbackResult>;
+    oidcAuthorization?: ((destination: string) => IAuthorizationStrategy<OidcCallbackResult>) | undefined;
     /** Where the device flow shows the user its code. */
-    deviceCodePresenter?: (destination: string) => IDeviceCodePresenter;
+    deviceCodePresenter?: ((destination: string) => IDeviceCodePresenter) | undefined;
     /** `saml2_pure`: turns the SAMLResponse into the system's session cookies. */
-    samlCookies?: (destination: string) => (samlResponse: string) => Promise<string>;
+    samlCookies?: ((destination: string) => (samlResponse: string) => Promise<string>) | undefined;
     /** The replay store the SAML assertion validators share. */
-    assertionReplayStore?: (destination: string) => IAssertionReplayStore;
+    assertionReplayStore?: ((destination: string) => IAssertionReplayStore) | undefined;
+    /**
+     * How a destination's client authenticates to the authorization server, for
+     * every grant that authenticates one (`ClientAuthenticationGrant`). Called
+     * once per build of the destination's provider, with the client the key
+     * store answers and its certificate, read only if the strategy asks — and
+     * then re-read on every call, a change building a new provider.
+     *
+     * A given strategy always answers one, or throws: there is no "nothing"
+     * answer, so an explicit choice never falls back to the secret. A throw
+     * becomes a `DestinationConfigError` naming `clientAuthentication`, in fixed
+     * words. Absent: the client secret, as in 4.0.0, and nothing
+     * certificate-related is read. Shipped: `fromServiceKeyCertificate()`,
+     * `fromServiceKeySecret({ encoding })`.
+     *
+     * It applies to the providers the broker builds: `getProvider`'s, and the
+     * token API's `provider` factory, which gets its answer as a fourth
+     * argument (`TokenProviderClient`) for a grant that authenticates a client.
+     * An instance given as `provider` is already composed by the consumer, so
+     * the token API uses it as given and calls no strategy for it.
+     */
+    clientAuthentication?: ClientAuthenticationStrategy | undefined;
+    /**
+     * How the provider the broker builds for a destination renews: called once
+     * per build of every token row (the UAA, OIDC and SAML grants), with the
+     * destination and the grant it states; the answer is the provider's
+     * `renewal`, unchanged. Required for those rows — there is no default: a
+     * token row built without it is refused naming `renewal`. `() =>
+     * refreshThenLogin()` is what 4.x did; `refreshOnly()` never logs in. Not
+     * called for `basic`, `snc` or `none`, nor for the token API's `provider`,
+     * which brings its own.
+     */
+    renewal?: RenewalOption | undefined;
+    /**
+     * What a session write that did not land means — `'fail'`: the call that
+     * caused it fails (`unknown`, `persisting-tokens`), and while the
+     * destination's write is pending every `getProvider` / `getToken` /
+     * `refreshToken` of it retries the write first, and once more right before
+     * it succeeds, and is refused while it fails; `'continue'`: it is logged
+     * and the call goes on. Either way the write stays pending until the
+     * destination's next write or `flush()` — nothing retries it on its own.
+     * Required for every destination
+     * that writes a secret — a token row built by `getProvider`, and every call
+     * of the token API; no default.
+     */
+    onWriteFailure?: 'fail' | 'continue' | undefined;
+    /**
+     * Passed to every token provider the broker builds; on only for `true`
+     * itself — absent, `false`, `'true'` or `1` is off. Never read from the
+     * environment. With it, a provider's one debug line for a refused token
+     * request names the request's secrets in its prepared form (the first and
+     * last four characters around a length marker), never the server's text;
+     * the line goes to the broker's logger. A consumer's `provider` — an
+     * instance or what a factory builds — keeps its own setting.
+     */
+    authDebug?: boolean | undefined;
 }
 /**
  * AuthBroker manages authentication tokens for destinations
@@ -80,28 +193,37 @@ export declare class AuthBroker {
     private readonly serviceKeyStore;
     private readonly sessionStore;
     private readonly provider;
-    /** A consumer factory's providers: the promise of the build, as `built`. */
-    private readonly consumerBuilt;
+    /** Per (destination, path): the provider handed out while unchanged. */
+    private readonly resolvedRow;
+    private readonly resolvedConsumer;
     /**
-     * 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.
      */
-    private readonly built;
+    private readonly rowSlots;
+    private readonly consumerSlots;
+    /** The broker-wide slot every `flush()` caller joins. */
+    private readonly flushSlot;
+    /** Per (destination, path): the last generation a build took. */
+    private readonly generations;
+    /** Per (destination, path): the newest generation that queued a write. */
+    private readonly newestWriter;
     /**
-     * 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.
      */
-    private readonly failedWrites;
+    private readonly instanceRefused;
     private readonly authorization;
     private readonly oidcAuthorization;
     private readonly deviceCodePresenter;
     private readonly samlCookies;
     private readonly assertionReplayStore;
-    /** getProvider's writes of the session secret, retried on their own. */
+    private readonly clientAuthentication;
+    private readonly renewal;
+    private readonly onWriteFailure;
+    /** `config.authDebug === true`: what every token provider it builds is told. */
+    private readonly authDebug;
+    /** Every write of the session secret: one plain queue per destination. */
     private readonly writer;
     /**
      * @param config Stores and the provider (instance or factory)
@@ -114,26 +236,52 @@ export declare 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.
      */
-    getToken(destination: string): Promise<string>;
+    getToken(destination: string, options?: BrokerCallOptions): Promise<string>;
     /**
      * 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.
      */
-    refreshToken(destination: string): Promise<string>;
+    refreshToken(destination: string, options?: BrokerCallOptions): Promise<string>;
+    /**
+     * 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`.
+     */
     private obtain;
+    /**
+     * 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.
+     */
+    private settlePending;
     /**
      * 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
@@ -142,38 +290,93 @@ export declare class AuthBroker {
      * a 3.x setup, served as before.
      */
     private statedForTokens;
-    /** The token API on `getProvider`'s provider. */
+    /**
+     * The token API on the row path's provider — the one `getProvider` hands
+     * out, resolved the same way, never through `getProvider` itself.
+     */
     private obtainShared;
     /**
-     * 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.
      */
     private obtainFromConsumer;
-    /** The failure recorded for this result's write here, thrown as the store raised it. */
-    private throwFailedWrite;
     /**
-     * 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.
+     * 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.
+     */
+    private slotOf;
+    /** Whether a build of this path was ever committed for the destination. */
+    private everBuilt;
+    /** A committed build's generation, from its path's counter. */
+    private nextGeneration;
+    /**
+     * 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.
+     */
+    private submit;
+    /** This call's store reads: each source read at most once. */
+    private storeReads;
+    /**
+     * 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.
+     */
+    private resolveConsumer;
+    /**
+     * 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.
+     */
+    private buildConsumer;
+    /**
+     * 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.)
      */
-    private consumerProviderFor;
+    private consumerClientAuthentication;
     /**
-     * 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.
      */
-    private resolveAuthorizationConfig;
+    private readAuthorization;
+    /**
+     * 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.
+     */
+    private consumerInputs;
     /**
      * `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.
      */
-    private resolveServiceUrl;
+    private serviceUrlOf;
     /**
      * A store read where absence is an answer and anything else is not.
      *
@@ -207,54 +410,104 @@ export declare 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: string): Promise<IAuthProvider>;
+    getProvider(destination: string, options?: BrokerCallOptions): Promise<IAuthProvider>;
+    /**
+     * 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.
+     */
+    private resolveRow;
+    /**
+     * 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.
+     */
     private build;
+    /**
+     * 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.
+     */
+    private rowRefusal;
     /**
      * 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.
      */
     private boundOrDiscarded;
     /**
-     * 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(): Promise<void>;
+    flush(options?: BrokerCallOptions): Promise<void>;
     /**
-     * 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.
      */
@@ -262,8 +515,9 @@ export declare class AuthBroker {
     /**
      * 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: string): ITokenRefresher;
+    createTokenRefresher(destination: string, options?: BrokerCallOptions): ITokenRefresher;
 }
 //# sourceMappingURL=AuthBroker.d.ts.map

package/dist/AuthBroker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AuthBroker.d.ts","sourceRoot":"","sources":["../src/AuthBroker.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"AuthBroker.d.ts","sourceRoot":"","sources":["../src/AuthBroker.ts"],"names":[],"mappings":"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"}