@mcp-abap-adt/auth-broker 2.2.0 → 3.0.1

package/dist/AuthBroker.d.ts

@@ -1,144 +1,119 @@
 /**
- * Main AuthBroker class for managing JWT tokens based on destinations
+ * AuthBroker: tokens for a destination, from a provider, kept in a session store.
+ *
+ * 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
+ * and writes the answer back. Whether a token is still valid, whether to use the
+ * refresh token or log in, and how a login is conducted (browser, headless,
+ * pasted code) are the provider's decisions — made by its strategy — and the
+ * broker does not repeat or override any of them.
  */
-import type { ITokenRefresher } from '@mcp-abap-adt/interfaces-auth';
+import type { IRefreshableTokenProvider, ITokenRefresher } from '@mcp-abap-adt/interfaces-auth';
 import type { ILogger } from '@mcp-abap-adt/interfaces-utils';
-import type { ITokenProvider } from './providers';
 import type { IAuthorizationConfig, IConnectionConfig, IServiceKeyStore, ISessionStore } from './stores/interfaces';
 /**
- * Configuration object for AuthBroker constructor
+ * Builds the provider for one destination, from what the stores hold for it.
+ *
+ * - `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.
+ *
+ * Called once per destination; the broker keeps the provider it returns.
+ */
+export type TokenProviderFactory = (destination: string, authConfig: IAuthorizationConfig | null, connConfig: IConnectionConfig) => IRefreshableTokenProvider;
+/**
+ * Configuration object for the AuthBroker constructor
  */
 export interface AuthBrokerConfig {
-    /** Session store (required) - stores and retrieves session data */
+    /** Session store (required) — where tokens and the refresh token are kept */
     sessionStore: ISessionStore;
-    /** Service key store (optional) - stores and retrieves service keys */
+    /** Service key store (optional) — UAA credentials and the service URL */
     serviceKeyStore?: IServiceKeyStore;
-    /** Token provider (required) - handles token refresh and authentication flows through browser-based authorization (e.g., XSUAA provider) */
-    tokenProvider: ITokenProvider;
     /**
-     * Allow browser-based authentication (optional, default: true)
-     * When false, getToken() will throw BROWSER_AUTH_REQUIRED error instead of blocking on browser auth.
-     * Use this for headless/non-interactive environments (e.g., MCP stdio transport).
+     * The token provider, or a factory building one per destination.
+     *
+     * An instance is used as given, for every destination. A factory is seeded
+     * with what the stores hold for the destination (see `TokenProviderFactory`).
      */
-    allowBrowserAuth?: boolean;
+    provider: IRefreshableTokenProvider | TokenProviderFactory;
 }
 /**
- * AuthBroker manages JWT authentication tokens for destinations
+ * AuthBroker manages authentication tokens for destinations
  */
 export declare class AuthBroker {
-    private browser;
-    private logger;
-    private serviceKeyStore;
-    private sessionStore;
-    private tokenProvider;
-    private allowBrowserAuth;
-    /**
-     * Create a new AuthBroker instance
-     * @param config Configuration object with stores and token provider
-     *               - sessionStore: Store for session data (required)
-     *               - serviceKeyStore: Store for service keys (optional)
-     *               - tokenProvider: Token provider implementing ITokenProvider interface (required) - handles browser-based authorization
-     * @param browser Optional browser name for authentication (chrome, edge, firefox, system, headless, none).
-     *                Default: 'system' (system default browser).
-     *                Use 'headless' for SSH/remote sessions - logs URL and waits for manual callback.
-     *                Use 'none' for automated tests - logs URL and rejects immediately.
-     * @param logger Optional logger instance implementing ILogger interface. If not provided, uses no-op logger.
-     */
-    constructor(config: AuthBrokerConfig, browser?: string, logger?: ILogger);
+    private readonly logger;
+    private readonly serviceKeyStore;
+    private readonly sessionStore;
+    private readonly provider;
+    private readonly providers;
     /**
-     * Load session data (connection and authorization configs)
+     * @param config Stores and the provider (instance or factory)
+     * @param logger Optional logger. Nothing the broker logs contains a token.
      */
-    private loadSessionData;
+    constructor(config: AuthBrokerConfig, logger?: ILogger);
     /**
-     * Get serviceUrl from session or service key store
+     * 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.
      */
-    private getServiceUrl;
+    getToken(destination: string): Promise<string>;
     /**
-     * Get UAA credentials from session or service key
+     * 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.
      */
-    private getAuthorizationConfigFromServiceKey;
+    refreshToken(destination: string): Promise<string>;
+    private obtain;
+    private providerFor;
     /**
-     * Save token and config to session
+     * 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.
      */
-    private saveTokenToSession;
-    private requestTokens;
-    private persistTokenResult;
+    private resolveAuthorizationConfig;
+    private resolveServiceUrl;
     /**
-     * Get authentication token for destination.
-     * Uses tokenProvider for all authentication operations (browser-based authorization).
-     *
-     * **Flow:**
-     * **Step 0: Initialize Session with Token (if needed)**
-     * - Check if session has `authorizationToken` AND UAA credentials
-     * - If both are empty AND serviceKeyStore is available:
-     *   - Get UAA credentials from service key
-     *   - Use tokenProvider for browser-based authentication
-     *   - Save token and refresh token to session
-     *
-     * **Step 1: Token Validation**
-     * - If token exists in session, validate it (if provider supports validation)
-     * - If valid → return token
-     * - If invalid or no token → continue to refresh
+     * 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.
      *
-     * **Step 2: Refresh Token Flow**
-     * - Check if refresh token exists in session
-     * - If refresh token exists:
-     *   - Use tokenProvider to refresh token (browser-based or refresh grant)
-     *   - Save new token to session
-     *   - Return new token
-     * - Otherwise → proceed to Step 3
-     *
-     * **Step 3: New Token Flow**
-     * - Get UAA credentials from session or service key
-     * - Use tokenProvider for browser-based authentication
-     * - Save new token to session
-     * - Return new token
-     *
-     * **Important Notes:**
-     * - All authentication is handled by tokenProvider (e.g., XSUAA provider)
-     * - Provider uses browser-based authorization to ensure proper role assignment
-     * - Direct UAA HTTP requests are not used to avoid role assignment issues
-     *
-     * @param destination Destination name (e.g., "TRIAL")
-     * @returns Promise that resolves to JWT token string
-     * @throws Error if session initialization fails or authentication failed
+     * `ITokenResult.expiresAt` has no field in `IConnectionConfig` to go to; the
+     * provider seeded with the stored token reads the expiry from the JWT itself.
      */
-    getToken(destination: string): Promise<string>;
+    private persist;
     /**
-     * Force refresh token for destination.
-     * Uses refresh token from session if available, otherwise uses UAA credentials from session or service key.
-     * @param destination Destination name (e.g., "TRIAL")
-     * @returns Promise that resolves to new JWT token string
+     * A store read where absence is an answer and anything else is not.
+     *
+     * A store says "nothing here" with `null`, or with `FILE_NOT_FOUND`, and the
+     * flow goes on to the next source. Any other failure — a service key that is
+     * not valid JSON, a file the process may not read — is a different problem
+     * with a different fix, and reaches the caller as the store raised it. It
+     * used to be logged and answered as absent, so the caller saw only the
+     * consequence ("missing required field 'serviceUrl'") and went looking for a
+     * file that was there.
      */
-    refreshToken(destination: string): Promise<string>;
+    private read;
     /**
-     * Get authorization configuration for destination
-     * @param destination Destination name (e.g., "TRIAL")
-     * @returns Promise that resolves to IAuthorizationConfig or null if not found
+     * Authorization configuration for the destination: the session's, else the
+     * service key's, else null.
      */
     getAuthorizationConfig(destination: string): Promise<IAuthorizationConfig | null>;
     /**
-     * Get connection configuration for destination
-     * @param destination Destination name (e.g., "TRIAL")
-     * @returns Promise that resolves to IConnectionConfig or null if not found
+     * Connection configuration for the destination: the session's, else the
+     * service key's (which has URLs but no token), else null.
      */
     getConnectionConfig(destination: string): Promise<IConnectionConfig | null>;
     /**
-     * Create a token refresher for a specific destination.
-     *
-     * The token refresher is designed to be injected into JwtAbapConnection via DI,
-     * allowing the connection to handle token refresh transparently without knowing
-     * about authentication internals.
-     *
-     * **Usage:**
-     * ```typescript
-     * const broker = new AuthBroker(config);
-     * const tokenRefresher = broker.createTokenRefresher('TRIAL');
-     * const connection = new JwtAbapConnection(config, tokenRefresher);
-     * ```
-     *
-     * @param destination Destination name (e.g., "TRIAL")
-     * @returns ITokenRefresher implementation for the given destination
+     * An `ITokenRefresher` for one destination, for injection into a connection:
+     * `getToken()` is the broker's `getToken`, `refreshToken()` its forced
+     * `refreshToken`.
      */
     createTokenRefresher(destination: string): ITokenRefresher;
 }

package/dist/AuthBroker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AuthBroker.d.ts","sourceRoot":"","sources":["../src/AuthBroker.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,eAAe,EAEhB,MAAM,+BAA+B,CAAC;AAEvC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gCAAgC,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EACV,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACd,MAAM,qBAAqB,CAAC;AA8D7B;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,mEAAmE;IACnE,YAAY,EAAE,aAAa,CAAC;IAC5B,uEAAuE;IACvE,eAAe,CAAC,EAAE,gBAAgB,CAAC;IACnC,4IAA4I;IAC5I,aAAa,EAAE,cAAc,CAAC;IAC9B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;GAEG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,MAAM,CAAU;IACxB,OAAO,CAAC,eAAe,CAA+B;IACtD,OAAO,CAAC,YAAY,CAAgB;IACpC,OAAO,CAAC,aAAa,CAAiB;IACtC,OAAO,CAAC,gBAAgB,CAAU;IAElC;;;;;;;;;;;OAWG;gBACS,MAAM,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO;IAsFxE;;OAEG;YACW,eAAe;IA0D7B;;OAEG;YACW,aAAa;IAoD3B;;OAEG;YACW,oCAAoC;IA4ClD;;OAEG;YACW,kBAAkB;YA4ClB,aAAa;YA0Db,kBAAkB;IAkDhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACG,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAsLpD;;;;;OAKG;IACG,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IASxD;;;;OAIG;IACG,sBAAsB,CAC1B,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IAoEvC;;;;OAIG;IACG,mBAAmB,CACvB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAuEpC;;;;;;;;;;;;;;;;OAgBG;IACH,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,eAAe;CAqB3D"}
+{"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"}