@mcp-abap-adt/auth-broker 3.1.0 → 4.1.0

package/dist/DestinationConfigError.d.ts

@@ -0,0 +1,27 @@
+/**
+ * A destination that lacks what its type needs.
+ *
+ * Thrown by `getProvider` before any provider is asked: a missing field is a
+ * fault no renewal cures, so it surfaces where the consumer builds its
+ * connector, not at the first `connect()`.
+ *
+ * **It carries names, never values.** `missingFields` holds store field names
+ * (`authType`, `username`, `sncQop`) or broker option names
+ * (`serviceKeyStore`, `provider`); the message is fixed wording plus the
+ * destination's name and those names. A stored value — a password, a token,
+ * even an `authType` that is not one of the four — never reaches it. There is
+ * no `cause`: a provider's own error quotes the value it refused (`qop … got
+ * '7'`), so it is not carried; its field names are mapped instead.
+ */
+export declare class DestinationConfigError extends Error {
+    readonly code: "DESTINATION_CONFIG";
+    readonly destination: string;
+    readonly missingFields: string[];
+    /**
+     * @param destination The destination's name, as the caller passed it.
+     * @param missingFields Field or option names only.
+     * @param reason Fixed wording: what is wrong, never a stored value.
+     */
+    constructor(destination: string, missingFields: string[], reason: string);
+}
+//# sourceMappingURL=DestinationConfigError.d.ts.map

package/dist/DestinationConfigError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DestinationConfigError.d.ts","sourceRoot":"","sources":["../src/DestinationConfigError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,IAAI,EAAG,oBAAoB,CAAU;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,EAAE,CAAC;IAEjC;;;;OAIG;gBACS,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM;CASzE"}

package/dist/DestinationConfigError.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DestinationConfigError = void 0;
+/**
+ * A destination that lacks what its type needs.
+ *
+ * Thrown by `getProvider` before any provider is asked: a missing field is a
+ * fault no renewal cures, so it surfaces where the consumer builds its
+ * connector, not at the first `connect()`.
+ *
+ * **It carries names, never values.** `missingFields` holds store field names
+ * (`authType`, `username`, `sncQop`) or broker option names
+ * (`serviceKeyStore`, `provider`); the message is fixed wording plus the
+ * destination's name and those names. A stored value — a password, a token,
+ * even an `authType` that is not one of the four — never reaches it. There is
+ * no `cause`: a provider's own error quotes the value it refused (`qop … got
+ * '7'`), so it is not carried; its field names are mapped instead.
+ */
+class DestinationConfigError extends Error {
+    code = 'DESTINATION_CONFIG';
+    destination;
+    missingFields;
+    /**
+     * @param destination The destination's name, as the caller passed it.
+     * @param missingFields Field or option names only.
+     * @param reason Fixed wording: what is wrong, never a stored value.
+     */
+    constructor(destination, missingFields, reason) {
+        super(`Destination "${destination}": ${reason} (${missingFields.join(', ')})`);
+        this.name = 'DestinationConfigError';
+        this.destination = destination;
+        this.missingFields = [...missingFields];
+        Object.setPrototypeOf(this, DestinationConfigError.prototype);
+    }
+}
+exports.DestinationConfigError = DestinationConfigError;

package/dist/SessionWriter.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The broker's writes of a destination's session secret, retried until the
+ * store takes them.
+ *
+ * A store failure is the storage's or a broker bug, never the token's, so it
+ * does not fail the authentication: the result stays pending for its
+ * destination and the writer tries again on its own — it does not wait for the
+ * provider to be called again, since a request may be the process's last.
+ *
+ * - **One pending result per destination, the latest.** A newer result
+ *   replaces the one waiting; an older one is never written after it.
+ * - **Attempts for one destination never overlap.** Each runs after the
+ *   previous one has settled.
+ * - **A growing delay:** one second after the first failure, doubling, capped
+ *   at one minute; reset once a write lands. The timer is `unref()`ed, so a
+ *   pending write never keeps a process alive.
+ * - **Failures are logged by class name** — never a message: the store holds
+ *   tokens, and its errors are foreign text.
+ * - **`flush()`** gives every pending result one more attempt and rejects,
+ *   naming the destinations, if any is still not written.
+ */
+import type { ILogger } from '@mcp-abap-adt/interfaces-utils';
+/** A thrown value's class, for a log line: never its message. */
+export declare function classLabel(error: unknown): string;
+/** `T`: what one write takes — the result, with what the broker writes beside it. */
+export declare class SessionWriter<T> {
+    private readonly write;
+    private readonly logger;
+    private readonly queues;
+    /**
+     * @param write Writes one result for a destination; throws when the store
+     *   does not take it.
+     */
+    constructor(write: (destination: string, result: T) => Promise<void>, logger: ILogger);
+    /**
+     * Take a new result for the destination and try to write it now. Never
+     * throws: resolves once this attempt has settled, written or left pending.
+     */
+    submit(destination: string, result: T): Promise<void>;
+    /**
+     * One more attempt for every pending result; resolves when all are written,
+     * rejects naming the destinations still pending — each failure as its
+     * destination and its error's class only, never the store's message. The
+     * retries go on after a rejection.
+     */
+    flush(): Promise<void>;
+    private queueOf;
+    /** Runs after the destination's previous attempt; never rejects. */
+    private attempt;
+    private writePending;
+    private schedule;
+    private cancelTimer;
+}
+//# sourceMappingURL=SessionWriter.d.ts.map

package/dist/SessionWriter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionWriter.d.ts","sourceRoot":"","sources":["../src/SessionWriter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gCAAgC,CAAC;AAgB9D,iEAAiE;AACjE,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAKjD;AAED,qFAAqF;AACrF,qBAAa,aAAa,CAAC,CAAC;IAQxB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IARzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+B;IAEtD;;;OAGG;gBAEgB,KAAK,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,EACxD,MAAM,EAAE,OAAO;IAGlC;;;OAGG;IACG,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAO3D;;;;;OAKG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAyB5B,OAAO,CAAC,OAAO;IASf,oEAAoE;IACpE,OAAO,CAAC,OAAO;YAMD,YAAY;IAgC1B,OAAO,CAAC,QAAQ;IAUhB,OAAO,CAAC,WAAW;CAMpB"}

package/dist/SessionWriter.js

@@ -0,0 +1,135 @@
+"use strict";
+/**
+ * The broker's writes of a destination's session secret, retried until the
+ * store takes them.
+ *
+ * A store failure is the storage's or a broker bug, never the token's, so it
+ * does not fail the authentication: the result stays pending for its
+ * destination and the writer tries again on its own — it does not wait for the
+ * provider to be called again, since a request may be the process's last.
+ *
+ * - **One pending result per destination, the latest.** A newer result
+ *   replaces the one waiting; an older one is never written after it.
+ * - **Attempts for one destination never overlap.** Each runs after the
+ *   previous one has settled.
+ * - **A growing delay:** one second after the first failure, doubling, capped
+ *   at one minute; reset once a write lands. The timer is `unref()`ed, so a
+ *   pending write never keeps a process alive.
+ * - **Failures are logged by class name** — never a message: the store holds
+ *   tokens, and its errors are foreign text.
+ * - **`flush()`** gives every pending result one more attempt and rejects,
+ *   naming the destinations, if any is still not written.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionWriter = void 0;
+exports.classLabel = classLabel;
+const FIRST_DELAY_MS = 1_000;
+const MAX_DELAY_MS = 60_000;
+/** A thrown value's class, for a log line: never its message. */
+function classLabel(error) {
+    if (error instanceof Error) {
+        return error.constructor?.name || 'Error';
+    }
+    return typeof error;
+}
+/** `T`: what one write takes — the result, with what the broker writes beside it. */
+class SessionWriter {
+    write;
+    logger;
+    queues = new Map();
+    /**
+     * @param write Writes one result for a destination; throws when the store
+     *   does not take it.
+     */
+    constructor(write, logger) {
+        this.write = write;
+        this.logger = logger;
+    }
+    /**
+     * Take a new result for the destination and try to write it now. Never
+     * throws: resolves once this attempt has settled, written or left pending.
+     */
+    async submit(destination, result) {
+        const queue = this.queueOf(destination);
+        queue.pending = result;
+        this.cancelTimer(queue);
+        await this.attempt(destination, queue);
+    }
+    /**
+     * One more attempt for every pending result; resolves when all are written,
+     * rejects naming the destinations still pending — each failure as its
+     * destination and its error's class only, never the store's message. The
+     * retries go on after a rejection.
+     */
+    async flush() {
+        const queues = [...this.queues];
+        await Promise.all(queues.map(([destination, queue]) => {
+            if (queue.pending === undefined)
+                return queue.tail;
+            this.cancelTimer(queue);
+            return this.attempt(destination, queue);
+        }));
+        const failed = queues.filter(([, queue]) => queue.pending !== undefined);
+        if (failed.length > 0) {
+            // The stores' own errors are not carried: their messages, causes and
+            // properties are foreign text that may quote what was being written.
+            throw new AggregateError(failed.map(([destination, queue]) => new Error(`"${destination}": ${classLabel(queue.lastError)}`)), `Session writes still failing for ${failed
+                .map(([destination]) => `"${destination}"`)
+                .join(', ')}; the broker keeps retrying them`);
+        }
+    }
+    queueOf(destination) {
+        let queue = this.queues.get(destination);
+        if (!queue) {
+            queue = { tail: Promise.resolve(), failures: 0 };
+            this.queues.set(destination, queue);
+        }
+        return queue;
+    }
+    /** Runs after the destination's previous attempt; never rejects. */
+    attempt(destination, queue) {
+        const run = queue.tail.then(() => this.writePending(destination, queue));
+        queue.tail = run;
+        return run;
+    }
+    async writePending(destination, queue) {
+        const result = queue.pending;
+        if (result === undefined)
+            return;
+        try {
+            await this.write(destination, result);
+        }
+        catch (error) {
+            queue.failures += 1;
+            queue.lastError = error;
+            const delay = Math.min(FIRST_DELAY_MS * 2 ** (queue.failures - 1), MAX_DELAY_MS);
+            this.logger.warn(`[AuthBroker] Session write for ${destination} failed; the token stands, the write is retried in ${delay} ms`, { error: classLabel(error), attempt: queue.failures });
+            this.schedule(destination, queue, delay);
+            return;
+        }
+        queue.failures = 0;
+        queue.lastError = undefined;
+        // A newer result that arrived meanwhile stays pending: its own attempt is
+        // queued after this one.
+        if (queue.pending === result) {
+            queue.pending = undefined;
+            this.cancelTimer(queue);
+        }
+    }
+    schedule(destination, queue, delay) {
+        this.cancelTimer(queue);
+        const timer = setTimeout(() => {
+            queue.timer = undefined;
+            void this.attempt(destination, queue);
+        }, delay);
+        timer.unref();
+        queue.timer = timer;
+    }
+    cancelTimer(queue) {
+        if (queue.timer) {
+            clearTimeout(queue.timer);
+            queue.timer = undefined;
+        }
+    }
+}
+exports.SessionWriter = SessionWriter;

package/dist/binding.d.ts

@@ -0,0 +1,117 @@
+/**
+ * A secret is bound to the resource it was obtained for and to who issued it.
+ *
+ * The session store keeps two strings beside the secret — `issuedFor`, the
+ * resource, and `issuedBy`, the issuer and its client — and the broker uses a
+ * stored secret only when both equal what this destination's means give. The
+ * store keeps them as given; the broker canonicalises **both sides** before it
+ * compares, with the one function here (the broker's only, decided), so a store
+ * need not canonicalise and a legacy file's composed URI compares equal.
+ *
+ * The canonical URI:
+ * - scheme and host lower-cased (by `URL`, for http and https);
+ * - the port explicit — `443` for `https`, `80` for `http` when the URL has
+ *   none; another scheme keeps the port it states;
+ * - the path without a trailing `/` (the root path is empty), its case kept;
+ * - one query parameter at most — `sap-client=<n>` for a resource,
+ *   `client_id=<id>` for an issuer, none for a SAML ACS — parsed and
+ *   re-encoded with `URLSearchParams`, so a value percent-encoded on one side
+ *   and plain on the other compares equal;
+ * - no user info, no other parameter, no fragment.
+ *
+ * A URL that does not parse, or has no host, has no canonical form: the
+ * binding is then absent, never guessed.
+ */
+import type { IConfig, IConnectionConfig } from '@mcp-abap-adt/interfaces-auth-broker';
+import type { IAuthorizationConfig } from '@mcp-abap-adt/interfaces-auth-sap';
+/** What a binding reads of a client: who it is, never its secret. */
+export type BoundClient = Pick<IAuthorizationConfig, 'uaaUrl' | 'uaaClientId'>;
+/**
+ * The resource: `serviceUrl` with the SAP client as `sap-client` — the
+ * destination's `sapClient` when it states one, over a `sap-client` already in
+ * the URL. For a stored value, call it without `sapClient`.
+ */
+export declare function resourceUri(serviceUrl: unknown, sapClient?: string): string | undefined;
+/**
+ * The issuer and its client: the authorization server's base URL with
+ * `client_id`. For a stored value, call it without `clientId`.
+ */
+export declare function issuerUri(issuerUrl: unknown, clientId?: string): string | undefined;
+/** The ACS of the system that set SAML session cookies: origin and path. */
+export declare function acsUri(acsUrl: unknown): string | undefined;
+/** How a stored `issuedBy` is read: as an issuer with its client, or as an ACS. */
+export type IssuerKind = 'issuer' | 'acs';
+/** What this destination's means bind a secret to, canonical; absent where they cannot say. */
+export interface Binding {
+    issuedFor?: string;
+    issuedBy?: string;
+    /** How the stored `issuedBy` is canonicalised before it is compared. */
+    issuerKind: IssuerKind;
+    /**
+     * The means state an issuer — for a `none` row, whether `issuedBy` is
+     * compared at all. True even when the stated URL does not parse: then it
+     * matches nothing.
+     */
+    issuerStated: boolean;
+    /**
+     * Set on the `clientAuthentication` strategy path only: a resource neither
+     * side states — no `issuedFor` computed (no service URL, or one that does
+     * not parse, as the CLI's XSUAA placeholder) and none stored — matches, so
+     * the issuer and client alone decide. A resource stated on one side only
+     * never matches. Without it (the 4.0.0 path) an absent resource matches
+     * nothing.
+     */
+    unstatedResourceMatches?: true;
+}
+/**
+ * The UAA grants (`authorization_code`, `client_credentials`, `passcode`) and
+ * `saml2_bearer`, whose token UAA issues to its client: the resource, and `uaaUrl` with `uaaClientId` — both required to match.
+ */
+export declare function uaaBinding(means: IConnectionConfig, client: BoundClient | null): Binding;
+/**
+ * The OIDC grants: the resource, and the issuer — `oidcIssuerUrl`, else
+ * `uaaUrl` — with `uaaClientId`; both required to match. Means that state
+ * neither issuer (explicit endpoints alone) bind no stored secret: one is then
+ * never seeded.
+ */
+export declare function oidcBinding(means: IConnectionConfig, client: BoundClient | null): Binding;
+/**
+ * `saml2_pure`: the resource, and the ACS of the system that sets the
+ * cookies — `samlAcsUrl`, origin and path; both required to match.
+ */
+export declare function samlPureBinding(means: IConnectionConfig): Binding;
+/**
+ * The token API with a consumer's provider: what the broker handed
+ * that provider — the `serviceUrl` it resolved, with the SAP client, and for a
+ * factory the client it resolved (`uaaUrl` with `uaaClientId`). An instance is
+ * handed no client, so no issuer is claimed for what it obtains: `issuedBy` is
+ * then absent, and `getProvider` never seeds from that secret.
+ */
+export declare function consumerBinding(serviceUrl: string, sapClient: string | undefined, client: BoundClient | null): Binding;
+/**
+ * A binding on the `clientAuthentication` strategy path: a resource that
+ * neither the means nor the stored session state matches, so the issuer and
+ * client alone decide (`Binding.unstatedResourceMatches`).
+ */
+export declare function strategyBinding(binding: Binding): Binding;
+/**
+ * A `none` row: the resource always; the issuer only when the means state one
+ * — `oidcIssuerUrl` (with `uaaClientId` when stated) or the client (`uaaUrl`
+ * and `uaaClientId`) for `jwt`, `samlAcsUrl` for `saml`.
+ */
+export declare function handedOverBinding(authType: 'jwt' | 'saml', means: IConnectionConfig, client: BoundClient | null): Binding;
+/**
+ * The stored `issuedFor`, canonicalised, equals the destination's — or, with
+ * `unstatedResourceMatches`, neither states one.
+ */
+export declare function sameResource(stored: IConfig | null, binding: Binding): boolean;
+/** The stored `issuedBy`, canonicalised as the destination's kind, equals it. */
+export declare function sameIssuer(stored: IConfig | null, binding: Binding): boolean;
+/**
+ * An obtained secret is this destination's only when **both** stored values
+ * equal the computed ones; either absent, on either side, is not a match —
+ * save a resource absent on both sides of a strategy-path binding
+ * (`unstatedResourceMatches`).
+ */
+export declare function boundHere(stored: IConfig | null, binding: Binding): boolean;
+//# sourceMappingURL=binding.d.ts.map

package/dist/binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../src/binding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EACV,OAAO,EACP,iBAAiB,EAClB,MAAM,sCAAsC,CAAC;AAC9C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAE9E,qEAAqE;AACrE,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,oBAAoB,EAAE,QAAQ,GAAG,aAAa,CAAC,CAAC;AA6C/E;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,OAAO,EACnB,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,GAAG,SAAS,CAEpB;AAED;;;GAGG;AACH,wBAAgB,SAAS,CACvB,SAAS,EAAE,OAAO,EAClB,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,CAEpB;AAED,4EAA4E;AAC5E,wBAAgB,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAE1D;AAED,mFAAmF;AACnF,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,KAAK,CAAC;AAE1C,+FAA+F;AAC/F,MAAM,WAAW,OAAO;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,UAAU,EAAE,UAAU,CAAC;IACvB;;;;OAIG;IACH,YAAY,EAAE,OAAO,CAAC;IACtB;;;;;;;OAOG;IACH,uBAAuB,CAAC,EAAE,IAAI,CAAC;CAChC;AAUD;;;GAGG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,iBAAiB,EACxB,MAAM,EAAE,WAAW,GAAG,IAAI,GACzB,OAAO,CAUT;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,iBAAiB,EACxB,MAAM,EAAE,WAAW,GAAG,IAAI,GACzB,OAAO,CAWT;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAOjE;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,MAAM,EAAE,WAAW,GAAG,IAAI,GACzB,OAAO,CAET;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAEzD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,KAAK,GAAG,MAAM,EACxB,KAAK,EAAE,iBAAiB,EACxB,MAAM,EAAE,WAAW,GAAG,IAAI,GACzB,OAAO,CA4BT;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,OAAO,GAAG,IAAI,EACtB,OAAO,EAAE,OAAO,GACf,OAAO,CAOT;AAED,iFAAiF;AACjF,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAI5E;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAE3E"}

package/dist/binding.js

@@ -0,0 +1,223 @@
+"use strict";
+/**
+ * A secret is bound to the resource it was obtained for and to who issued it.
+ *
+ * The session store keeps two strings beside the secret — `issuedFor`, the
+ * resource, and `issuedBy`, the issuer and its client — and the broker uses a
+ * stored secret only when both equal what this destination's means give. The
+ * store keeps them as given; the broker canonicalises **both sides** before it
+ * compares, with the one function here (the broker's only, decided), so a store
+ * need not canonicalise and a legacy file's composed URI compares equal.
+ *
+ * The canonical URI:
+ * - scheme and host lower-cased (by `URL`, for http and https);
+ * - the port explicit — `443` for `https`, `80` for `http` when the URL has
+ *   none; another scheme keeps the port it states;
+ * - the path without a trailing `/` (the root path is empty), its case kept;
+ * - one query parameter at most — `sap-client=<n>` for a resource,
+ *   `client_id=<id>` for an issuer, none for a SAML ACS — parsed and
+ *   re-encoded with `URLSearchParams`, so a value percent-encoded on one side
+ *   and plain on the other compares equal;
+ * - no user info, no other parameter, no fragment.
+ *
+ * A URL that does not parse, or has no host, has no canonical form: the
+ * binding is then absent, never guessed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resourceUri = resourceUri;
+exports.issuerUri = issuerUri;
+exports.acsUri = acsUri;
+exports.uaaBinding = uaaBinding;
+exports.oidcBinding = oidcBinding;
+exports.samlPureBinding = samlPureBinding;
+exports.consumerBinding = consumerBinding;
+exports.strategyBinding = strategyBinding;
+exports.handedOverBinding = handedOverBinding;
+exports.sameResource = sameResource;
+exports.sameIssuer = sameIssuer;
+exports.boundHere = boundHere;
+/** The default port a URL without one is taken to mean. */
+const DEFAULT_PORTS = {
+    'https:': '443',
+    'http:': '80',
+};
+function present(value) {
+    return typeof value === 'string' && value !== '';
+}
+/**
+ * The canonical URI of `raw`, keeping only the query parameter `param` — its
+ * value `override` when given, else the one `raw` carries.
+ */
+function canonical(raw, param, override) {
+    if (!present(raw))
+        return undefined;
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return undefined;
+    }
+    // `URL` lower-cases the scheme, and the host of an http(s) URL. Another
+    // scheme's host is kept as written: no form beyond http(s) is defined yet.
+    const host = url.hostname;
+    if (host === '')
+        return undefined;
+    const scheme = url.protocol;
+    const port = url.port || DEFAULT_PORTS[scheme] || '';
+    const path = url.pathname.replace(/\/+$/, '');
+    let query = '';
+    if (param) {
+        const value = present(override) ? override : url.searchParams.get(param);
+        if (present(value)) {
+            query = `?${new URLSearchParams([[param, value]]).toString()}`;
+        }
+    }
+    return `${scheme}//${host}${port ? `:${port}` : ''}${path}${query}`;
+}
+/**
+ * The resource: `serviceUrl` with the SAP client as `sap-client` — the
+ * destination's `sapClient` when it states one, over a `sap-client` already in
+ * the URL. For a stored value, call it without `sapClient`.
+ */
+function resourceUri(serviceUrl, sapClient) {
+    return canonical(serviceUrl, 'sap-client', sapClient);
+}
+/**
+ * The issuer and its client: the authorization server's base URL with
+ * `client_id`. For a stored value, call it without `clientId`.
+ */
+function issuerUri(issuerUrl, clientId) {
+    return canonical(issuerUrl, 'client_id', clientId);
+}
+/** The ACS of the system that set SAML session cookies: origin and path. */
+function acsUri(acsUrl) {
+    return canonical(acsUrl, undefined);
+}
+/** The resource the means name: `serviceUrl` with `sapClient`. */
+function resourceOf(means) {
+    return resourceUri(means.serviceUrl, present(means.sapClient) ? means.sapClient : undefined);
+}
+/**
+ * The UAA grants (`authorization_code`, `client_credentials`, `passcode`) and
+ * `saml2_bearer`, whose token UAA issues to its client: the resource, and `uaaUrl` with `uaaClientId` — both required to match.
+ */
+function uaaBinding(means, client) {
+    const stated = present(client?.uaaUrl) && present(client?.uaaClientId);
+    return {
+        issuedFor: resourceOf(means),
+        issuedBy: stated
+            ? issuerUri(client?.uaaUrl, client?.uaaClientId)
+            : undefined,
+        issuerKind: 'issuer',
+        issuerStated: stated,
+    };
+}
+/**
+ * The OIDC grants: the resource, and the issuer — `oidcIssuerUrl`, else
+ * `uaaUrl` — with `uaaClientId`; both required to match. Means that state
+ * neither issuer (explicit endpoints alone) bind no stored secret: one is then
+ * never seeded.
+ */
+function oidcBinding(means, client) {
+    const issuer = present(means.oidcIssuerUrl)
+        ? means.oidcIssuerUrl
+        : client?.uaaUrl;
+    const stated = present(issuer) && present(client?.uaaClientId);
+    return {
+        issuedFor: resourceOf(means),
+        issuedBy: stated ? issuerUri(issuer, client?.uaaClientId) : undefined,
+        issuerKind: 'issuer',
+        issuerStated: stated,
+    };
+}
+/**
+ * `saml2_pure`: the resource, and the ACS of the system that sets the
+ * cookies — `samlAcsUrl`, origin and path; both required to match.
+ */
+function samlPureBinding(means) {
+    return {
+        issuedFor: resourceOf(means),
+        issuedBy: acsUri(means.samlAcsUrl),
+        issuerKind: 'acs',
+        issuerStated: present(means.samlAcsUrl),
+    };
+}
+/**
+ * The token API with a consumer's provider: what the broker handed
+ * that provider — the `serviceUrl` it resolved, with the SAP client, and for a
+ * factory the client it resolved (`uaaUrl` with `uaaClientId`). An instance is
+ * handed no client, so no issuer is claimed for what it obtains: `issuedBy` is
+ * then absent, and `getProvider` never seeds from that secret.
+ */
+function consumerBinding(serviceUrl, sapClient, client) {
+    return uaaBinding({ serviceUrl, sapClient }, client);
+}
+/**
+ * A binding on the `clientAuthentication` strategy path: a resource that
+ * neither the means nor the stored session state matches, so the issuer and
+ * client alone decide (`Binding.unstatedResourceMatches`).
+ */
+function strategyBinding(binding) {
+    return { ...binding, unstatedResourceMatches: true };
+}
+/**
+ * A `none` row: the resource always; the issuer only when the means state one
+ * — `oidcIssuerUrl` (with `uaaClientId` when stated) or the client (`uaaUrl`
+ * and `uaaClientId`) for `jwt`, `samlAcsUrl` for `saml`.
+ */
+function handedOverBinding(authType, means, client) {
+    const issuedFor = resourceOf(means);
+    if (authType === 'saml') {
+        return {
+            issuedFor,
+            issuedBy: acsUri(means.samlAcsUrl),
+            issuerKind: 'acs',
+            issuerStated: present(means.samlAcsUrl),
+        };
+    }
+    const clientId = present(client?.uaaClientId)
+        ? client.uaaClientId
+        : undefined;
+    if (present(means.oidcIssuerUrl)) {
+        return {
+            issuedFor,
+            issuedBy: issuerUri(means.oidcIssuerUrl, clientId),
+            issuerKind: 'issuer',
+            issuerStated: true,
+        };
+    }
+    const stated = present(client?.uaaUrl) && clientId !== undefined;
+    return {
+        issuedFor,
+        issuedBy: stated ? issuerUri(client?.uaaUrl, clientId) : undefined,
+        issuerKind: 'issuer',
+        issuerStated: stated,
+    };
+}
+/**
+ * The stored `issuedFor`, canonicalised, equals the destination's — or, with
+ * `unstatedResourceMatches`, neither states one.
+ */
+function sameResource(stored, binding) {
+    if (binding.issuedFor === undefined) {
+        return (binding.unstatedResourceMatches === true && !present(stored?.issuedFor));
+    }
+    return resourceUri(stored?.issuedFor) === binding.issuedFor;
+}
+/** The stored `issuedBy`, canonicalised as the destination's kind, equals it. */
+function sameIssuer(stored, binding) {
+    if (binding.issuedBy === undefined)
+        return false;
+    const read = binding.issuerKind === 'acs' ? acsUri : issuerUri;
+    return read(stored?.issuedBy) === binding.issuedBy;
+}
+/**
+ * An obtained secret is this destination's only when **both** stored values
+ * equal the computed ones; either absent, on either side, is not a match —
+ * save a resource absent on both sides of a strategy-path binding
+ * (`unstatedResourceMatches`).
+ */
+function boundHere(stored, binding) {
+    return sameResource(stored, binding) && sameIssuer(stored, binding);
+}

package/dist/bindingOf.d.ts

@@ -0,0 +1,37 @@
+/**
+ * What a destination's means bind its secret to: the one
+ * place the broker chooses which binding a destination has. `getProvider`
+ * builds each provider with it, and `persist` writes what it gives beside every
+ * secret; `bindingOf` hands the same to a consumer.
+ */
+import type { DestinationGrant, IConnectionConfig } from '@mcp-abap-adt/interfaces-auth-broker';
+import type { IAuthorizationConfig } from '@mcp-abap-adt/interfaces-auth-sap';
+import type { BoundClient } from './binding';
+import { type Binding } from './binding';
+/**
+ * The binding of a `jwt` or `saml` destination with the grant it states: the
+ * UAA grants and `saml2_bearer` by `uaaUrl` and the client, the OIDC grants by
+ * the issuer and the client, `saml2_pure` by its ACS, and `none` by what the
+ * means state.
+ */
+export declare function destinationBinding(authType: 'jwt' | 'saml', grant: DestinationGrant, means: IConnectionConfig, client: BoundClient | null): Binding;
+/** The two strings a session store keeps beside a secret; absent where the means cannot say. */
+export interface SecretBinding {
+    issuedFor?: string;
+    issuedBy?: string;
+}
+/**
+ * The binding the broker writes beside a secret for a destination with these
+ * means and this client — canonical, exactly what `getProvider` compares a
+ * stored secret against. For a consumer that hands over a credential the
+ * broker cannot obtain (a `none` destination: a token or cookies it was
+ * given) and writes it to the session store itself: written with this binding,
+ * `getProvider` presents it; written with any other, it refuses.
+ *
+ * `means` are the key store's (`authType`, `grantType`, `serviceUrl`,
+ * `sapClient`, the issuer or ACS); `client` is the key store's client, when the
+ * destination has one. A destination that states no `jwt` / `saml` type or no
+ * grant binds nothing: `{}`. Never logs, never throws.
+ */
+export declare function bindingOf(means: IConnectionConfig, client?: IAuthorizationConfig | null): SecretBinding;
+//# sourceMappingURL=bindingOf.d.ts.map

package/dist/bindingOf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindingOf.d.ts","sourceRoot":"","sources":["../src/bindingOf.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,sCAAsC,CAAC;AAC9C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EACL,KAAK,OAAO,EAKb,MAAM,WAAW,CAAC;AAGnB;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,KAAK,GAAG,MAAM,EACxB,KAAK,EAAE,gBAAgB,EACvB,KAAK,EAAE,iBAAiB,EACxB,MAAM,EAAE,WAAW,GAAG,IAAI,GACzB,OAAO,CAKT;AAED,gGAAgG;AAChG,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,iBAAiB,EACxB,MAAM,GAAE,oBAAoB,GAAG,IAAW,GACzC,aAAa,CAcf"}