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

package/dist/AuthBroker.d.ts

@@ -1,5 +1,15 @@
 /**
- * AuthBroker: tokens for a destination, from a provider, kept in a session store.
+ * AuthBroker: the credential for a destination, and tokens for one.
+ *
+ * `getProvider` builds the `IAuthProvider` a destination states, from the
+ * means its service key store holds and the secret its session store holds.
+ * Every token provider it builds writes what it obtains back to the session
+ * store through `onTokens` — the secret alone, retried by the broker when the
+ * store fails (`SessionWriter`); `flush()` reports what is still pending.
+ * The token API (`getToken`, `refreshToken`, `createTokenRefresher`) asks that
+ * same provider — one per destination, shared — or, when the consumer gives
+ * one, the consumer's provider, whose every answer it writes through the same
+ * path.
  *
  * The broker orchestrates and nothing more. It resolves what the stores know
  * about a destination, hands it to the provider, asks the provider for a token
@@ -8,7 +18,8 @@
  * pasted code) are the provider's decisions — made by its strategy — and the
  * broker does not repeat or override any of them.
  */
-import type { IRefreshableTokenProvider, ITokenRefresher } from '@mcp-abap-adt/interfaces-auth';
+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 { ILogger } from '@mcp-abap-adt/interfaces-utils';
 import type { IAuthorizationConfig, IConnectionConfig, IServiceKeyStore, ISessionStore } from './stores/interfaces';
 /**
@@ -24,21 +35,42 @@ import type { IAuthorizationConfig, IConnectionConfig, IServiceKeyStore, ISessio
  * Called once per destination; the broker keeps the provider it returns.
  */
 export type TokenProviderFactory = (destination: string, authConfig: IAuthorizationConfig | null, connConfig: IConnectionConfig) => IRefreshableTokenProvider;
+/** The grants whose provider takes an `IAuthorizationStrategy<string>`. */
+export type StrategyGrant = 'authorization_code' | 'passcode' | 'saml2_pure' | 'saml2_bearer';
 /**
  * Configuration object for the AuthBroker constructor
  */
 export interface AuthBrokerConfig {
-    /** Session store (required) — where tokens and the refresh token are kept */
+    /**
+     * Session store (required) — the session secret: the token or cookies,
+     * `expiresAt`, the refresh token.
+     */
     sessionStore: ISessionStore;
-    /** Service key store (optional) — UAA credentials and the service URL */
+    /**
+     * Service key store — the means: `authType`, `grantType`, the client,
+     * basic's user and password, the SNC fields, `serviceUrl`. `getProvider`
+     * needs it: there is no other source of means.
+     */
     serviceKeyStore?: IServiceKeyStore;
     /**
-     * The token provider, or a factory building one per destination.
+     * 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`).
      */
-    provider: IRefreshableTokenProvider | TokenProviderFactory;
+    provider?: IRefreshableTokenProvider | TokenProviderFactory;
+    /** The interactive strategy of the UAA code, passcode and SAML grants. */
+    authorization?: (destination: string, grant: StrategyGrant) => IAuthorizationStrategy<string>;
+    /** The interactive strategy of the OIDC authorization code grant. */
+    oidcAuthorization?: (destination: string) => IAuthorizationStrategy<OidcCallbackResult>;
+    /** Where the device flow shows the user its code. */
+    deviceCodePresenter?: (destination: string) => IDeviceCodePresenter;
+    /** `saml2_pure`: turns the SAMLResponse into the system's session cookies. */
+    samlCookies?: (destination: string) => (samlResponse: string) => Promise<string>;
+    /** The replay store the SAML assertion validators share. */
+    assertionReplayStore?: (destination: string) => IAssertionReplayStore;
 }
 /**
  * AuthBroker manages authentication tokens for destinations
@@ -48,7 +80,29 @@ export declare class AuthBroker {
     private readonly serviceKeyStore;
     private readonly sessionStore;
     private readonly provider;
-    private readonly providers;
+    /** A consumer factory's providers: the promise of the build, as `built`. */
+    private readonly consumerBuilt;
+    /**
+     * 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.
+     */
+    private readonly built;
+    /**
+     * 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.
+     */
+    private readonly failedWrites;
+    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 writer;
     /**
      * @param config Stores and the provider (instance or factory)
      * @param logger Optional logger. Nothing the broker logs contains a token.
@@ -58,36 +112,68 @@ export declare class AuthBroker {
      * A token for the destination: the provider's current one, which it refreshes
      * or obtains by login when it judges the cached one unusable.
      *
-     * The result is written to the session store. Errors from the provider
-     * (its typed errors included) propagate unchanged.
+     * Without a consumer `provider`, the provider is the one `getProvider` hands
+     * out for the destination — the same instance, so one token and one renewal
+     * serve both — and what it obtains is written by its `onTokens`. With one,
+     * the consumer's provider is asked and its answer written, as in 3.x — the
+     * secret alone.
+     *
+     * Errors from the provider (its typed errors included) propagate unchanged;
+     * so does a store failure, a failed write of the token included — the token
+     * stands and the broker keeps retrying the write.
+     *
+     * @throws DestinationConfigError for a destination the key store states as
+     *   `basic` or `snc`, before any provider is asked; without a consumer
+     *   `provider`, also for one whose provider obtains no token.
      */
     getToken(destination: string): 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()`,
-     * writes the result to the session store and returns it.
+     * token the server has just refused. Calls the provider's `refreshTokens()`;
+     * a renewal already in flight for the destination is joined, not repeated.
      */
     refreshToken(destination: string): Promise<string>;
     private obtain;
-    private providerFor;
     /**
-     * The credentials the provider is built with: the session's own when it holds
-     * them, else the service key's, carrying the refresh token the session
-     * stored. The session keeps a refresh token without credentials when the
-     * credentials came from the service key, since the broker does not copy the
-     * client secret into it; `loadSession` is where such a token is read.
+     * The destination's means, read first: a destination the key store states
+     * as `basic` or `snc` holds no token, so the token API refuses it before any
+     * provider is asked — it would write a token over a credential that is not
+     * one. A key store that states no `authType`, or no key store, is
+     * a 3.x setup, served as before.
+     */
+    private statedForTokens;
+    /** The token API on `getProvider`'s provider. */
+    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.
+     */
+    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.
+     */
+    private consumerProviderFor;
+    /**
+     * The credentials a consumer's factory is built with: the session's own when
+     * it holds them, else the service key's, carrying the refresh token the
+     * session stored — the 3.x order. A session store of auth-stores 3
+     * answers no client, so the key store's is what is found.
      */
     private resolveAuthorizationConfig;
-    private resolveServiceUrl;
     /**
-     * Writes the result by its type: a SAML result is session cookies, anything
-     * else a bearer token. The refresh token is written only when the result has
-     * one, so a provider that returns none does not erase the stored one.
-     *
-     * `ITokenResult.expiresAt` has no field in `IConnectionConfig` to go to; the
-     * provider seeded with the stored token reads the expiry from the JWT itself.
+     * `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 persist;
+    private resolveServiceUrl;
     /**
      * A store read where absence is an answer and anything else is not.
      *
@@ -101,15 +187,78 @@ export declare class AuthBroker {
      */
     private read;
     /**
-     * Authorization configuration for the destination: the session's, else the
-     * service key's, else null.
+     * The destination's client: the service key store's `uaaUrl`, `uaaClientId`
+     * and `uaaClientSecret`, with the refresh token the session stores laid over
+     * them; `null` when the key store has no client. A client a session store
+     * answers is not read, nor a refresh token a key store answers.
      */
     getAuthorizationConfig(destination: string): Promise<IAuthorizationConfig | null>;
     /**
-     * Connection configuration for the destination: the session's, else the
-     * service key's (which has URLs but no token), else null.
+     * The destination's connection config: the service key store's means with
+     * the session's secret (`authorizationToken`, `sessionCookies`,
+     * `expiresAt`) and its binding (`issuedFor`, `issuedBy`) laid over them; `null` when neither store holds anything.
+     * Means a session store answers are not read, nor a secret a key store
+     * answers.
      */
     getConnectionConfig(destination: string): Promise<IConnectionConfig | null>;
+    /**
+     * The credential for the destination, ready for a connector: the provider
+     * its configuration states (`authType`, and `grantType` for `jwt` / `saml`),
+     * built from the means the service key store holds and the secret the
+     * session store holds.
+     *
+     * One provider per destination for the broker's life: concurrent first calls
+     * share one build, and a build that threw is tried again on the next call.
+     *
+     * A token provider (the UAA, OIDC and SAML grants) is seeded from the
+     * session when the stored secret is bound to this destination, and writes
+     * every token it obtains — at `prepare()`, on expiry, or in `rejected()` after
+     * a 401 — back to the session store before it answers (see `flush()`).
+     *
+     * @throws DestinationConfigError when the destination lacks what its type
+     *   needs — naming the fields or options, never a value.
+     */
+    getProvider(destination: string): Promise<IAuthProvider>;
+    private build;
+    /**
+     * 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.
+     */
+    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.
+     */
+    flush(): 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.
+     *
+     * - `expiresAt`: fixed by `onTokens` when the result arrived — the result's
+     *   own, else the `expiresIn` it reports counted from then (the rule the
+     *   provider applies to its own cache).
+     * - `refreshToken`: the result's, else the one the session holds, read at
+     *   write time, so a result without one does not erase the stored one — for
+     *   a provider the broker built, only a stored one bound where this one is:
+     *   a refresh token obtained for another resource or from another client is
+     *   not carried into this secret. A consumer's provider was seeded
+     *   with whatever the session held, so whatever it holds is carried.
+     * - `issuedFor` / `issuedBy`: the binding computed when the provider was
+     *   built, each left out when the means lack its source — so the
+     *   store clears it.
+     * - A destination the key store now states as `basic` or `snc` is not
+     *   written: those obtain no session secret.
+     */
+    private writeSecret;
     /**
      * An `ITokenRefresher` for one destination, for injection into a connection:
      * `getToken()` is the broker's `getToken`, `refreshToken()` its forced

package/dist/AuthBroker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AuthBroker.d.ts","sourceRoot":"","sources":["../src/AuthBroker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,yBAAyB,EACzB,eAAe,EAEhB,MAAM,+BAA+B,CAAC;AAEvC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gCAAgC,CAAC;AAC9D,OAAO,KAAK,EACV,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACd,MAAM,qBAAqB,CAAC;AAS7B;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,oBAAoB,GAAG,CACjC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,oBAAoB,GAAG,IAAI,EACvC,UAAU,EAAE,iBAAiB,KAC1B,yBAAyB,CAAC;AAE/B;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6EAA6E;IAC7E,YAAY,EAAE,aAAa,CAAC;IAC5B,yEAAyE;IACzE,eAAe,CAAC,EAAE,gBAAgB,CAAC;IACnC;;;;;OAKG;IACH,QAAQ,EAAE,yBAAyB,GAAG,oBAAoB,CAAC;CAC5D;AAUD;;GAEG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IACjC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA+B;IAC/D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAgB;IAC7C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmD;IAC5E,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgD;IAE1E;;;OAGG;gBACS,MAAM,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,OAAO;IA2DtD;;;;;;OAMG;IACG,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIpD;;;;OAIG;IACG,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;YAI1C,MAAM;YA2BN,WAAW;IA4BzB;;;;;;OAMG;YACW,0BAA0B;YAiC1B,iBAAiB;IAuB/B;;;;;;;OAOG;YACW,OAAO;IAoDrB;;;;;;;;;;OAUG;YACW,IAAI;IAgBlB;;;OAGG;IACG,sBAAsB,CAC1B,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IAkBvC;;;OAGG;IACG,mBAAmB,CACvB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAkBpC;;;;OAIG;IACH,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,eAAe;CAM3D"}
+{"version":3,"file":"AuthBroker.d.ts","sourceRoot":"","sources":["../src/AuthBroker.ts"],"names":[],"mappings":"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"}