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

package/dist/clientAuthentication.d.ts

@@ -0,0 +1,124 @@
+/**
+ * How a destination's client authenticates to the authorization server — the
+ * consumer's choice, as a strategy (`AuthBrokerConfig.clientAuthentication`).
+ *
+ * The broker ships two factories, each failing closed: one answers the
+ * certificate the key store holds, one the secret. Neither falls back to the
+ * other; a consumer that wants a fallback composes it, and its order is the
+ * consumer's statement. Whatever a strategy throws, the broker turns into a
+ * `DestinationConfigError` in fixed words (`resolveClientAuthentication`),
+ * carrying the thrown value as auth-errors reads it — never its message, no
+ * `cause`.
+ */
+import type { IClientAuthentication } from '@mcp-abap-adt/interfaces-auth';
+import type { IClientCertificate } from '@mcp-abap-adt/interfaces-auth-broker';
+import type { IAuthorizationConfig } from '@mcp-abap-adt/interfaces-auth-sap';
+/**
+ * Every grant whose client authenticates to the authorization server: the
+ * three UAA grants, the OIDC grants and `saml2_bearer`. (`saml2_pure` and the
+ * basic, SNC and handed-over rows authenticate no client and never call the
+ * strategy.)
+ */
+export type ClientAuthenticationGrant = 'client_credentials' | 'authorization_code' | 'passcode' | 'oidc_authorization_code' | 'device_code' | 'password' | 'token_exchange' | 'saml2_bearer';
+/** What a strategy is given, once per build of a destination's provider. */
+export interface ClientAuthenticationContext {
+    readonly destination: string;
+    readonly grant: ClientAuthenticationGrant;
+    /**
+     * The secret client the key store's `getAuthorizationConfig` answered —
+     * `uaaUrl`, `uaaClientId`, `uaaClientSecret` only, never a refresh token —
+     * or null.
+     */
+    readonly client: IAuthorizationConfig | null;
+    /**
+     * The key store's certificate client, read only when called and at most
+     * once per build; `null` when the store has none or implements no
+     * `getClientCertificate`.
+     */
+    readCertificate(): Promise<IClientCertificate | null>;
+    /**
+     * The build's attempt: aborts when every caller waiting on the build has
+     * gone. A strategy that waits on the network — a loader's
+     * `tlsMaterial()` — ends its wait on it; the broker sets no bound of its
+     * own.
+     */
+    readonly signal: AbortSignal;
+}
+/** The strategy `AuthBrokerConfig.clientAuthentication` takes. */
+export type ClientAuthenticationStrategy = (context: ClientAuthenticationContext) => Promise<IClientAuthentication>;
+/**
+ * `tls_client_auth` with the certificate and key the key store holds, against
+ * `${certUrl}/oauth/token`. The material is handed over as given and checked
+ * before the factory answers — auth-providers checks it only on first use, so
+ * a malformed, incomplete or expired PEM would otherwise surface only at the
+ * first token request, in a provider already built and cached. What
+ * `tlsMaterial()` throws — auth-providers' `client-certificate` failure — is
+ * carried by the guard as auth-errors reads it.
+ *
+ * Throws "the destination has no client certificate" when the store answers
+ * `null` or implements no `getClientCertificate`.
+ */
+export declare function fromServiceKeyCertificate(): ClientAuthenticationStrategy;
+/** How `fromServiceKeySecret` writes the client id and secret. */
+export interface FromServiceKeySecretOptions {
+    /**
+     * `'raw'`: `base64(id:secret)` as given — XSUAA accepts only this
+     * (measured). `'form'`: each component form-encoded first (RFC 6749
+     * §2.3.1) — UAA, Keycloak. Required: it depends on the server.
+     */
+    readonly encoding: 'raw' | 'form';
+}
+/**
+ * `client_secret_basic` with the secret client the key store holds.
+ *
+ * Throws "the destination has no client secret" when the store answers no
+ * secret client, or one with an empty secret. A missing or unknown `encoding`
+ * is refused when the factory is made.
+ */
+export declare function fromServiceKeySecret(options: FromServiceKeySecretOptions): ClientAuthenticationStrategy;
+/**
+ * What a strategy is told of the secret client: an allowlist — who it is
+ * (`uaaUrl`, `uaaClientId`) and its secret (`uaaClientSecret`, which
+ * `fromServiceKeySecret` sends) — never a refresh token or any other field a
+ * store's `getAuthorizationConfig` carried, which no binding has checked.
+ */
+export declare function contextClient(client: IAuthorizationConfig | null): IAuthorizationConfig | null;
+/**
+ * The context for one build: the client through `contextClient`;
+ * `readCertificate` lazy and memoised — the first call reads, every later one
+ * gets the same answer; `signal`, the build's attempt.
+ */
+export declare function clientAuthenticationContext(destination: string, grant: ClientAuthenticationGrant, client: IAuthorizationConfig | null, read: () => Promise<IClientCertificate | null>, signal: AbortSignal): ClientAuthenticationContext;
+/**
+ * Runs the strategy inside the guard. Any throw — the strategy's own, a
+ * store's, a malformed PEM — and any answer that is no client authentication
+ * becomes a `DestinationConfigError` naming `clientAuthentication`, in fixed
+ * words. A shipped factory's own refusal keeps the broker's words; anything
+ * else is "the clientAuthentication strategy failed", carrying
+ * `readFailure(thrown, 'client-authentication-strategy')` — a provider's
+ * failure (an unusable certificate) as the provider made it, a strategy's own
+ * error only as its classification. No `cause`, no message of the thrown
+ * value.
+ */
+export declare function resolveClientAuthentication(strategy: ClientAuthenticationStrategy, context: ClientAuthenticationContext): Promise<IClientAuthentication>;
+/**
+ * Who the client is — its authorization server and client id — and nothing
+ * else: no secret field, so it can never be taken for a (public) secret
+ * client, and never PEM.
+ */
+export interface ClientIdentity {
+    readonly uaaUrl: string;
+    readonly uaaClientId: string;
+}
+/**
+ * The client identity a strategy-authenticated row and its binding take: the
+ * secret client's `uaaUrl` and `uaaClientId` when the key store has one, else
+ * the certificate client's `uaaUrl` and `clientId` — read through the
+ * context's memoised `readCertificate`, so at most once per build — else
+ * `null`. The secret stays behind: beside a strategy a row passes none.
+ *
+ * A failing read is a `DestinationConfigError` naming `clientAuthentication`
+ * in fixed words — nothing of what the store threw, no `cause`.
+ */
+export declare function clientIdentity(context: ClientAuthenticationContext): Promise<ClientIdentity | null>;
+//# sourceMappingURL=clientAuthentication.d.ts.map

package/dist/clientAuthentication.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clientAuthentication.d.ts","sourceRoot":"","sources":["../src/clientAuthentication.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAC3E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAC/E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAG9E;;;;;GAKG;AACH,MAAM,MAAM,yBAAyB,GACjC,oBAAoB,GACpB,oBAAoB,GACpB,UAAU,GACV,yBAAyB,GACzB,aAAa,GACb,UAAU,GACV,gBAAgB,GAChB,cAAc,CAAC;AAEnB,4EAA4E;AAC5E,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,yBAAyB,CAAC;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAC7C;;;;OAIG;IACH,eAAe,IAAI,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;IACtD;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED,kEAAkE;AAClE,MAAM,MAAM,4BAA4B,GAAG,CACzC,OAAO,EAAE,2BAA2B,KACjC,OAAO,CAAC,qBAAqB,CAAC,CAAC;AAgCpC;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,IAAI,4BAA4B,CAgBxE;AAED,kEAAkE;AAClE,MAAM,WAAW,2BAA2B;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,KAAK,GAAG,MAAM,CAAC;CACnC;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,2BAA2B,GACnC,4BAA4B,CAc9B;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,oBAAoB,GAAG,IAAI,GAClC,oBAAoB,GAAG,IAAI,CAO7B;AAmBD;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,yBAAyB,EAChC,MAAM,EAAE,oBAAoB,GAAG,IAAI,EACnC,IAAI,EAAE,MAAM,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,EAC9C,MAAM,EAAE,WAAW,GAClB,2BAA2B,CAY7B;AAcD;;;;;;;;;;GAUG;AACH,wBAAsB,2BAA2B,CAC/C,QAAQ,EAAE,4BAA4B,EACtC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,qBAAqB,CAAC,CAkChC;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAiBhC"}

package/dist/clientAuthentication.js

@@ -0,0 +1,218 @@
+"use strict";
+/**
+ * How a destination's client authenticates to the authorization server — the
+ * consumer's choice, as a strategy (`AuthBrokerConfig.clientAuthentication`).
+ *
+ * The broker ships two factories, each failing closed: one answers the
+ * certificate the key store holds, one the secret. Neither falls back to the
+ * other; a consumer that wants a fallback composes it, and its order is the
+ * consumer's statement. Whatever a strategy throws, the broker turns into a
+ * `DestinationConfigError` in fixed words (`resolveClientAuthentication`),
+ * carrying the thrown value as auth-errors reads it — never its message, no
+ * `cause`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fromServiceKeyCertificate = fromServiceKeyCertificate;
+exports.fromServiceKeySecret = fromServiceKeySecret;
+exports.contextClient = contextClient;
+exports.clientAuthenticationContext = clientAuthenticationContext;
+exports.resolveClientAuthentication = resolveClientAuthentication;
+exports.clientIdentity = clientIdentity;
+const auth_errors_1 = require("@mcp-abap-adt/auth-errors");
+const auth_providers_1 = require("@mcp-abap-adt/auth-providers");
+const DestinationConfigError_1 = require("./DestinationConfigError");
+const NO_CERTIFICATE = 'the destination has no client certificate';
+const NO_SECRET = 'the destination has no client secret';
+/**
+ * The shipped factories' refusals, and what each lacks: recognised by
+ * identity in this module-private map — never by `instanceof` or a property
+ * of the thrown value — so nothing outside this file can make one, and a
+ * consumer that catches and alters one changes nothing the guard reads.
+ */
+const unavailable = new WeakMap();
+function clientUnavailable(missing) {
+    const error = new Error(missing === 'certificate' ? NO_CERTIFICATE : NO_SECRET);
+    unavailable.set(error, missing);
+    return error;
+}
+/**
+ * `value` without the slashes it ends with, in one backwards pass: linear in
+ * the length, whatever the store answered — no regular expression on a
+ * stored value.
+ */
+function withoutTrailingSlashes(value) {
+    let end = value.length;
+    while (end > 0 && value.charCodeAt(end - 1) === 0x2f)
+        end -= 1;
+    return value.slice(0, end);
+}
+/**
+ * `tls_client_auth` with the certificate and key the key store holds, against
+ * `${certUrl}/oauth/token`. The material is handed over as given and checked
+ * before the factory answers — auth-providers checks it only on first use, so
+ * a malformed, incomplete or expired PEM would otherwise surface only at the
+ * first token request, in a provider already built and cached. What
+ * `tlsMaterial()` throws — auth-providers' `client-certificate` failure — is
+ * carried by the guard as auth-errors reads it.
+ *
+ * Throws "the destination has no client certificate" when the store answers
+ * `null` or implements no `getClientCertificate`.
+ */
+function fromServiceKeyCertificate() {
+    return async (context) => {
+        const certificate = await context.readCertificate();
+        if (!certificate) {
+            throw clientUnavailable('certificate');
+        }
+        const authentication = (0, auth_providers_1.tlsClientCertificate)({
+            material: { cert: certificate.certificate, key: certificate.key },
+            endpoint: `${withoutTrailingSlashes(certificate.certUrl)}/oauth/token`,
+        });
+        if (typeof authentication.tlsMaterial !== 'function') {
+            throw clientUnavailable('certificate');
+        }
+        await authentication.tlsMaterial();
+        return authentication;
+    };
+}
+/**
+ * `client_secret_basic` with the secret client the key store holds.
+ *
+ * Throws "the destination has no client secret" when the store answers no
+ * secret client, or one with an empty secret. A missing or unknown `encoding`
+ * is refused when the factory is made.
+ */
+function fromServiceKeySecret(options) {
+    const encoding = options?.encoding;
+    if (encoding !== 'raw' && encoding !== 'form') {
+        throw new TypeError("fromServiceKeySecret: encoding must be 'raw' or 'form'");
+    }
+    return async (context) => {
+        const secret = context.client?.uaaClientSecret;
+        if (typeof secret !== 'string' || secret.length === 0) {
+            throw clientUnavailable('secret');
+        }
+        return (0, auth_providers_1.clientSecretBasic)(secret, { encoding });
+    };
+}
+/**
+ * What a strategy is told of the secret client: an allowlist — who it is
+ * (`uaaUrl`, `uaaClientId`) and its secret (`uaaClientSecret`, which
+ * `fromServiceKeySecret` sends) — never a refresh token or any other field a
+ * store's `getAuthorizationConfig` carried, which no binding has checked.
+ */
+function contextClient(client) {
+    if (!client)
+        return null;
+    return {
+        uaaUrl: client.uaaUrl,
+        uaaClientId: client.uaaClientId,
+        uaaClientSecret: client.uaaClientSecret,
+    };
+}
+/**
+ * The certificate client as the contract declares it — `uaaUrl`, `clientId`,
+ * `certificate`, `key`, `certUrl` — and nothing else a store answered with it.
+ */
+function certificateOf(answer) {
+    if (!answer)
+        return null;
+    return {
+        uaaUrl: answer.uaaUrl,
+        clientId: answer.clientId,
+        certificate: answer.certificate,
+        key: answer.key,
+        certUrl: answer.certUrl,
+    };
+}
+/**
+ * The context for one build: the client through `contextClient`;
+ * `readCertificate` lazy and memoised — the first call reads, every later one
+ * gets the same answer; `signal`, the build's attempt.
+ */
+function clientAuthenticationContext(destination, grant, client, read, signal) {
+    let certificate;
+    return {
+        destination,
+        grant,
+        client: contextClient(client),
+        readCertificate: () => {
+            certificate ??= read().then(certificateOf);
+            return certificate;
+        },
+        signal,
+    };
+}
+const FAILED = 'the clientAuthentication strategy failed';
+const REFUSED = 'the clientAuthentication strategy refused';
+/** A shipped factory's refusal: the broker's own words, by what it lacks. */
+function unavailableWords(error) {
+    if (typeof error !== 'object' || error === null)
+        return undefined;
+    const missing = unavailable.get(error);
+    if (missing === 'certificate')
+        return `${REFUSED}: ${NO_CERTIFICATE}`;
+    if (missing === 'secret')
+        return `${REFUSED}: ${NO_SECRET}`;
+    return undefined;
+}
+/**
+ * Runs the strategy inside the guard. Any throw — the strategy's own, a
+ * store's, a malformed PEM — and any answer that is no client authentication
+ * becomes a `DestinationConfigError` naming `clientAuthentication`, in fixed
+ * words. A shipped factory's own refusal keeps the broker's words; anything
+ * else is "the clientAuthentication strategy failed", carrying
+ * `readFailure(thrown, 'client-authentication-strategy')` — a provider's
+ * failure (an unusable certificate) as the provider made it, a strategy's own
+ * error only as its classification. No `cause`, no message of the thrown
+ * value.
+ */
+async function resolveClientAuthentication(strategy, context) {
+    let answer;
+    let usable;
+    try {
+        answer = await strategy(context);
+        // Read inside the guard: a getter on the answer may throw too.
+        usable =
+            typeof answer === 'object' &&
+                answer !== null &&
+                typeof answer.authenticate === 'function';
+    }
+    catch (error) {
+        const words = unavailableWords(error);
+        if (words !== undefined) {
+            throw new DestinationConfigError_1.DestinationConfigError(context.destination, ['clientAuthentication'], words);
+        }
+        throw new DestinationConfigError_1.DestinationConfigError(context.destination, ['clientAuthentication'], FAILED, (0, auth_errors_1.readFailure)(error, 'client-authentication-strategy'));
+    }
+    if (!usable) {
+        throw new DestinationConfigError_1.DestinationConfigError(context.destination, ['clientAuthentication'], 'the clientAuthentication strategy answered no client authentication');
+    }
+    return answer;
+}
+/**
+ * The client identity a strategy-authenticated row and its binding take: the
+ * secret client's `uaaUrl` and `uaaClientId` when the key store has one, else
+ * the certificate client's `uaaUrl` and `clientId` — read through the
+ * context's memoised `readCertificate`, so at most once per build — else
+ * `null`. The secret stays behind: beside a strategy a row passes none.
+ *
+ * A failing read is a `DestinationConfigError` naming `clientAuthentication`
+ * in fixed words — nothing of what the store threw, no `cause`.
+ */
+async function clientIdentity(context) {
+    const client = context.client;
+    if (client) {
+        return { uaaUrl: client.uaaUrl, uaaClientId: client.uaaClientId };
+    }
+    let certificate;
+    try {
+        certificate = await context.readCertificate();
+    }
+    catch {
+        throw new DestinationConfigError_1.DestinationConfigError(context.destination, ['clientAuthentication'], 'the client certificate could not be read');
+    }
+    if (!certificate)
+        return null;
+    return { uaaUrl: certificate.uaaUrl, uaaClientId: certificate.clientId };
+}

package/dist/contractShape.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The shape of a contract object as this package has always built it.
+ *
+ * The contract packages (`@mcp-abap-adt/interfaces-auth`, `-auth-broker`,
+ * `-auth-sap`) and `@mcp-abap-adt/auth-providers` declare their optional
+ * fields `?: T`, which under `exactOptionalPropertyTypes` means "absent, never
+ * `undefined`". The broker builds those objects — a provider's configuration,
+ * the session it writes, the client it hands a consumer factory — with an
+ * optional field that has no value present and set to `undefined`
+ * (`refreshToken: undefined`), and a store, a provider or a consumer may
+ * depend on the key being there (`'refreshToken' in config`, `Object.keys`,
+ * `{ ...stored, ...secret }`). The key's presence is behaviour, kept as it was.
+ */
+/** `T` whose optional fields may also hold an explicit `undefined`. */
+export type WithUndefined<T> = {
+    [K in keyof T]: T[K] | (undefined extends T[K] ? undefined : never);
+};
+/**
+ * The contract type of an object built with explicit `undefined`s. The one
+ * assertion between the two shapes: every field still has the contract's
+ * type, and no field is added or dropped.
+ */
+export declare function asContract<T>(value: WithUndefined<T>): T;
+//# sourceMappingURL=contractShape.d.ts.map

package/dist/contractShape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contractShape.d.ts","sourceRoot":"","sources":["../src/contractShape.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,uEAAuE;AACvE,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI;KAC5B,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,GAAG,KAAK,CAAC;CACpE,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,CAExD"}

package/dist/contractShape.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * The shape of a contract object as this package has always built it.
+ *
+ * The contract packages (`@mcp-abap-adt/interfaces-auth`, `-auth-broker`,
+ * `-auth-sap`) and `@mcp-abap-adt/auth-providers` declare their optional
+ * fields `?: T`, which under `exactOptionalPropertyTypes` means "absent, never
+ * `undefined`". The broker builds those objects — a provider's configuration,
+ * the session it writes, the client it hands a consumer factory — with an
+ * optional field that has no value present and set to `undefined`
+ * (`refreshToken: undefined`), and a store, a provider or a consumer may
+ * depend on the key being there (`'refreshToken' in config`, `Object.keys`,
+ * `{ ...stored, ...secret }`). The key's presence is behaviour, kept as it was.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asContract = asContract;
+/**
+ * The contract type of an object built with explicit `undefined`s. The one
+ * assertion between the two shapes: every field still has the contract's
+ * type, and no field is added or dropped.
+ */
+function asContract(value) {
+    return value;
+}