@mcp-abap-adt/auth-broker 1.0.8 → 2.1.0

package/LICENSE

@@ -1,22 +1,165 @@
-MIT License
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
 
-Copyright (c) 2025 Oleksii Kyslytsia
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+  0. Additional Definitions.
 
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

package/README.md

@@ -26,13 +26,16 @@ AuthBroker requires a token provider configured for the destination:
 
 ```typescript
 import { AuthBroker, AbapSessionStore } from '@mcp-abap-adt/auth-broker';
-import { AuthorizationCodeProvider } from '@mcp-abap-adt/auth-providers';
+import {
+  AuthorizationCodeProvider,
+  browserCallbackStrategy,
+} from '@mcp-abap-adt/auth-providers';
 
 const tokenProvider = new AuthorizationCodeProvider({
   uaaUrl: 'https://...authentication...hana.ondemand.com',
   clientId: '...',
   clientSecret: '...',
-  browser: 'system',
+  authorization: browserCallbackStrategy({ browser: 'system' }),
 });
 
 const broker = new AuthBroker({
@@ -53,7 +56,10 @@ import {
   AbapServiceKeyStore,
   AbapSessionStore,
 } from '@mcp-abap-adt/auth-broker';
-import { AuthorizationCodeProvider } from '@mcp-abap-adt/auth-providers';
+import {
+  AuthorizationCodeProvider,
+  browserCallbackStrategy,
+} from '@mcp-abap-adt/auth-providers';
 
 const broker = new AuthBroker({
   sessionStore: new AbapSessionStore('/path/to/destinations'),
@@ -62,7 +68,7 @@ const broker = new AuthBroker({
     uaaUrl: 'https://...authentication...hana.ondemand.com',
     clientId: '...',
     clientSecret: '...',
-    browser: 'system',
+    authorization: browserCallbackStrategy({ browser: 'system' }),
   }),
 }, 'chrome', logger);
 
@@ -74,7 +80,7 @@ const brokerNoBrowser = new AuthBroker({
     uaaUrl: 'https://...authentication...hana.ondemand.com',
     clientId: '...',
     clientSecret: '...',
-    browser: 'none',
+    authorization: browserCallbackStrategy({ browser: 'none' }),
   }),
   allowBrowserAuth: false, // Throws BROWSER_AUTH_REQUIRED if browser auth needed
 }, 'chrome', logger);
@@ -92,7 +98,7 @@ const broker = new AuthBroker({
     uaaUrl: 'https://...authentication...hana.ondemand.com',
     clientId: '...',
     clientSecret: '...',
-    browser: 'system',
+    authorization: browserCallbackStrategy({ browser: 'system' }),
   }),
 });
 ```
@@ -111,7 +117,13 @@ const broker = new AuthBroker({
 
 ### Custom Browser Auth Port
 
-To avoid port conflicts with browser authentication:
+How a login is conducted — including which port the local OAuth2 callback
+listens on — is an `IAuthorizationStrategy` passed as `authorization`, not a
+field on the provider config. `browserCallbackStrategy` from
+`@mcp-abap-adt/auth-providers` builds the ready-made one; its default port is
+`61001`, chosen to sit well clear of the range application servers and
+proxies typically use (e.g. `3001`/`3333`). Pass `port` to avoid conflicts
+with a specific redirect URI registered at the identity provider:
 
 ```typescript
 const broker = new AuthBroker({
@@ -121,8 +133,7 @@ const broker = new AuthBroker({
     uaaUrl: 'https://...authentication...hana.ondemand.com',
     clientId: '...',
     clientSecret: '...',
-    browser: 'system',
-    redirectPort: 4001,
+    authorization: browserCallbackStrategy({ browser: 'system', port: 4001 }),
   }),
 }, 'chrome');
 ```
@@ -572,10 +583,13 @@ The package uses the `ITokenProvider` interface for token acquisition. Provider
   - No refresh token provided
 
 - **`AuthorizationCodeProvider`** - For BTP/ABAP authentication (full scope)
-  - Constructor accepts optional `browserAuthPort?: number` parameter (default: 3001)
-  - Automatically finds an available port if the requested port is in use (prevents `EADDRINUSE` errors)
-  - Server properly closes all connections and frees the port after authentication completes
-  - Use custom port to avoid conflicts when running alongside other services (e.g., proxy server)
+  - How the login is conducted is an `authorization?: IAuthorizationStrategy<string>`, not a
+    provider field. Omitted, it defaults to a browser callback on port `61001`
+  - `browserCallbackStrategy({ browser?, port?, timeoutMs? })` from `@mcp-abap-adt/auth-providers`
+    builds the ready-made strategy; pass `port` to avoid conflicts when running alongside other
+    services (e.g. a proxy server) or to match a redirect URI registered at the identity provider
+  - The callback port is held only for the duration of a login and released when it ends —
+    by success, failure, timeout, or cancellation
   - Uses browser-based OAuth2 flow (if no refresh token)
   - Uses refresh token if available
   - Provides refresh token for future use
@@ -593,6 +607,7 @@ import {
 import {
   ClientCredentialsProvider,
   AuthorizationCodeProvider,
+  browserCallbackStrategy,
 } from '@mcp-abap-adt/auth-providers';
 
 // XSUAA authentication
@@ -623,7 +638,7 @@ const btpBroker = new AuthBroker({
     uaaUrl: 'https://auth.example.com',
     clientId: '...',
     clientSecret: '...',
-    browser: 'system',
+    authorization: browserCallbackStrategy({ browser: 'system' }),
   }),
 });
 
@@ -635,7 +650,7 @@ const btpBrokerFull = new AuthBroker({
     uaaUrl: 'https://auth.example.com',
     clientId: '...',
     clientSecret: '...',
-    browser: 'system',
+    authorization: browserCallbackStrategy({ browser: 'system' }),
   }),
 });
 ```
@@ -660,6 +675,14 @@ mcp-auth --service-key <path> --output <path> [--env <path>] [--type abap|xsuaa]
 - `none`: Show URL in console and wait for callback (no browser)
 - `system/chrome/edge/firefox`: Open specific browser
 
+`--browser` and `--redirect-port` are routed into `browserCallbackStrategy`. This CLI has no
+default of its own for the callback port: `--redirect-port` overrides it when given; omitted,
+the port comes from `auth-providers` (currently `61001`, chosen to sit above the ephemeral range
+and clear of the `3001`/`3333` range servers and proxies typically use). If you registered a
+redirect URI with a specific port at your identity provider, pass `--redirect-port` to match it.
+A login is given 5 minutes to complete (this is a person switching to a browser and signing in
+by hand, not an unattended caller).
+
 **Examples:**
 ```bash
 # Auth code (default via service key)
@@ -703,12 +726,22 @@ mcp-sso --protocol <oidc|saml2> --flow <flow> --output <path> [--type abap|xsuaa
 - OIDC: `browser`, `device`, `password`, `token_exchange`
 - SAML2: `bearer`, `pure`
 
+Only the flows that actually open a browser (OIDC `browser`; SAML2 `bearer`/`pure` with the
+default `--assertion-flow browser`) use `--browser` and `--redirect-port` — they are routed
+into `browserCallbackStrategy`/`oidcCallbackStrategy`/`samlCallbackStrategy`. This CLI has no
+default of its own for the callback port: `--redirect-port` overrides it when given; omitted,
+the port comes from `auth-providers` (currently `61001`). A login is given 5 minutes to
+complete. `device`, `password`, and `token_exchange` never open a browser from this process, so
+`--browser`/`--redirect-port` have no effect for them. This applies the same way whether
+`--protocol`/`--flow` come from CLI flags or from `--config` (below) — a field's origin doesn't
+change how it's handled, and CLI flags always take precedence over the same field in a file.
+
 **Examples:**
 ```bash
 # OIDC browser flow
 mcp-sso oidc --flow browser --issuer https://issuer --client-id my-client --output ./sso.env --type xsuaa
 
-# OIDC browser flow (manual code / OOB)
+# OIDC browser flow (manual code / OOB — no callback server is opened for this combination)
 mcp-sso oidc --flow browser --token-endpoint https://issuer/token --client-id my-client --code <auth_code> --redirect-uri urn:ietf:wg:oauth:2.0:oob --output ./sso.env --type xsuaa
 
 # OIDC device flow
@@ -765,7 +798,8 @@ It enables `authorization_code` and `saml2-bearer` grant types and provides a
 simple `CatalogService`. See `tests/sso-demo/readme.md` for deploy steps.
 
 **Config file:**
-You can pass a JSON file with provider config:
+You can pass a JSON file with provider config instead of (or alongside) `--protocol`/`--flow`
+and the OIDC/SAML flags — `--config` alone is enough to run a flow, with no other flags required:
 
 ```json
 {
@@ -777,6 +811,14 @@ You can pass a JSON file with provider config:
 }
 ```
 
+Any CLI flag given alongside `--config` overrides the same field in the file; a field the file
+sets and no flag overrides is used as-is. A file written for a pre-2.0.0 config still works:
+`browser` and `redirectPort` are routed into the strategy exactly as the equivalent CLI flags
+are, and `authorizationCode`/`assertionFlow` are honored the same way `--code`/`--assertion-flow`
+are. A file that sets `authorizationCodeProvider`, `assertionProvider`, or `manualInput` — all
+functions, which JSON cannot express — is refused with an error naming the CLI flag to use
+instead, rather than having the field silently dropped.
+
 ### Utility Script
 
 Generate `.env` files from service keys:
@@ -855,4 +897,26 @@ Thank you to all contributors! See [CONTRIBUTORS.md](CONTRIBUTORS.md) for the co
 
 ## License
 
-MIT
+**GNU Lesser General Public License v3.0 only** (`LGPL-3.0-only`).
+Earlier published versions were MIT and stay MIT — a licence change is not
+retroactive.
+
+Copyright © 2025–2026 Oleksii Kyslytsia
+
+This library is free software: you can redistribute it and/or modify it under the
+terms of the GNU Lesser General Public License as published by the Free Software
+Foundation, version 3.
+
+It is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+PURPOSE. See the GNU Lesser General Public License for more details.
+
+Both texts ship with the package and both are needed: [`LICENSE`](LICENSE) is the
+LGPL, [`COPYING`](COPYING) is the GPL it is written on top of, since the LGPL is a
+set of additional permissions over the GPL and cannot be read alone.
+
+**What this means if you depend on this package.** Linking it into your own
+program — importing it, as every consumer of an npm package does — does not put
+your program under the LGPL. What the licence asks is that changes *to this
+library* stay free, and that your users can replace it with their own build.
+

package/dist/bin/mcp-auth.js

@@ -61,6 +61,11 @@ const distPath = path.resolve(__dirname, '..', 'index.js');
 const { AuthBroker } = require(distPath);
 const auth_providers_1 = require("@mcp-abap-adt/auth-providers");
 const auth_stores_1 = require("@mcp-abap-adt/auth-stores");
+/**
+ * A person completes this login at a browser; the provider's own default
+ * (30s) is sized for an unattended caller instead.
+ */
+const INTERACTIVE_LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
 function getVersion() {
     try {
         const candidates = [
@@ -108,7 +113,8 @@ function showHelp() {
     console.log('                            - system/chrome/edge/firefox: Open specific browser');
     console.log('  --format <format>       Output format: json or env (default: env)');
     console.log('  --service-url <url>     Service URL (SAP URL for ABAP, MCP URL for XSUAA). For XSUAA, optional.');
-    console.log('  --redirect-port <port>  Port for OAuth redirect URI (default: 3001). Must match XSUAA redirect-uris config.');
+    console.log('  --redirect-port <port>  Port for OAuth redirect URI (default: from auth-providers, currently 61001).');
+    console.log('                          Must match XSUAA redirect-uris config.');
     console.log('');
     console.log('  --version, -v          Show version number');
     console.log('  --help, -h             Show this help message');
@@ -159,9 +165,9 @@ function showHelp() {
     console.log('    * none/headless: Show URL in console and wait for callback');
     console.log('    * system/chrome/edge/firefox: Open specific browser');
     console.log('  - Both providers (xsuaa and abap) support both flows');
-    console.log('  - --redirect-port: Port for OAuth redirect URI (default: 3001)');
+    console.log('  - --redirect-port: Port for OAuth redirect URI (default: from auth-providers, currently 61001)');
     console.log('    * Must match redirect_uri configured in XSUAA/ABAP OAuth2 settings');
-    console.log('    * Common values: 3001 (default), 8080 (SAP examples)');
+    console.log('    * If your registered redirect URI uses a different port (e.g. 3001, 8080), pass it explicitly');
     console.log('  - For XSUAA, serviceUrl (MCP URL) is optional - can be provided via --service-url or service key');
     console.log('  - For ABAP, serviceUrl (SAP URL) is required - can be provided via --service-url or service key');
     console.log('  - SAP_URL/XSUAA_MCP_URL is written to .env (from --service-url, service key, or placeholder)');
@@ -599,7 +605,12 @@ async function main() {
         }
         // Default: authorization_code flow with browser
         // --credential: client_credentials flow (no browser needed)
-        const redirectPort = options.redirectPort || 3001;
+        // The callback port is the provider's own choice (DEFAULT_CALLBACK_PORT,
+        // currently 61001) unless the user overrides it with --redirect-port.
+        // Only resolved to a concrete number here for the URL preview below —
+        // the strategy itself re-derives the same default independently when
+        // `port` is left undefined.
+        const redirectPort = options.redirectPort ?? auth_providers_1.DEFAULT_CALLBACK_PORT;
         // Log authorization URL for debugging
         if (!options.credential) {
             const redirectUri = `http://localhost:${redirectPort}/callback`;
@@ -618,8 +629,14 @@ async function main() {
                 clientId: authConfig.uaaClientId,
                 clientSecret: authConfig.uaaClientSecret,
                 refreshToken: authConfig.refreshToken,
-                browser: options.browser,
-                redirectPort: redirectPort,
+                // Passing `options.redirectPort` (not the resolved `redirectPort`
+                // above) so an omitted --redirect-port lets the strategy bind its
+                // own default rather than this CLI pinning a number it doesn't own.
+                authorization: (0, auth_providers_1.browserCallbackStrategy)({
+                    browser: options.browser,
+                    port: options.redirectPort,
+                    timeoutMs: INTERACTIVE_LOGIN_TIMEOUT_MS,
+                }),
             });
         const broker = new AuthBroker({
             sessionStore,