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

package/dist/destinations.js

@@ -5,21 +5,38 @@
  * Two fields choose the provider — `authType` and, for `jwt` and `saml`,
  * `grantType` — and nothing else: no field's presence or absence is ever
  * read to pick a row. Both come from the key store's means.
+ *
+ * Every token row takes the consumer's `renewal` (called once per build, with
+ * the destination and its grant) and persists through auth-providers'
+ * `refreshStatePersistence` over the broker's write, governed by the
+ * consumer's `onWriteFailure`; a row built without either is refused naming
+ * it, beside every other missing field, in one error. A failure the broker
+ * reads — the SNC provider's, a validator's, a provider constructor's — is
+ * read through auth-errors (`readFailure`) and carried by the
+ * `DestinationConfigError`, never matched by class.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isStatedRow = isStatedRow;
 exports.statedAuthType = statedAuthType;
 exports.statedGrant = statedGrant;
 exports.basicProvider = basicProvider;
 exports.sncProvider = sncProvider;
 exports.handedOverProvider = handedOverProvider;
+exports.isWriteFailurePolicy = isWriteFailurePolicy;
+exports.optionsLacking = optionsLacking;
 exports.isUaaGrant = isUaaGrant;
+exports.uaaRefusal = uaaRefusal;
 exports.uaaProvider = uaaProvider;
 exports.isOidcGrant = isOidcGrant;
+exports.oidcRefusal = oidcRefusal;
 exports.oidcProvider = oidcProvider;
 exports.isSamlGrant = isSamlGrant;
+exports.samlRefusal = samlRefusal;
 exports.samlProvider = samlProvider;
+const auth_errors_1 = require("@mcp-abap-adt/auth-errors");
 const auth_providers_1 = require("@mcp-abap-adt/auth-providers");
 const binding_1 = require("./binding");
+const contractShape_1 = require("./contractShape");
 const DestinationConfigError_1 = require("./DestinationConfigError");
 /** The allowed `authType` / `grantType` pairs. `basic` and `snc` read no grant. */
 const GRANTS = {
@@ -36,10 +53,39 @@ const GRANTS = {
     saml: ['saml2_pure', 'saml2_bearer', 'none'],
 };
 const AUTH_TYPES = ['basic', 'jwt', 'saml', 'snc'];
+/**
+ * `authType` and `grantType` are a `jwt` / `saml` pair of the closed list —
+ * so neither holds `;` or `/`. Never throws.
+ */
+function isStatedRow(authType, grant) {
+    if (authType !== 'jwt' && authType !== 'saml')
+        return false;
+    return GRANTS[authType].includes(grant);
+}
 /** A stored string that counts as present: `''` is missing. */
 function present(value) {
     return typeof value === 'string' && value !== '';
 }
+/** Not stated: absent or `null`. */
+function unstated(value) {
+    return value === undefined || value === null;
+}
+/**
+ * Whether a trust input the binding hashes has its expected shape —
+ * or is not stated. One of another shape is refused naming it, never hashed
+ * as if it were absent: two different malformed values would otherwise give
+ * one digest.
+ */
+function trustShaped(value, shape) {
+    if (unstated(value))
+        return true;
+    if (shape === 'string')
+        return typeof value === 'string';
+    if (shape === 'boolean')
+        return typeof value === 'boolean';
+    return (Array.isArray(value) &&
+        value.every((element) => typeof element === 'string'));
+}
 /** The stated `authType`, or the error naming it. */
 function statedAuthType(destination, means) {
     const authType = means?.authType;
@@ -64,6 +110,32 @@ function statedGrant(destination, authType, means) {
     }
     return grantType;
 }
+/** The secret a row's client holds; an identity holds none. */
+function secretOf(client) {
+    return client && 'uaaClientSecret' in client
+        ? client.uaaClientSecret
+        : undefined;
+}
+/** Added to a row's refusal when it has no client and no strategy was given. */
+const CERTIFICATE_HINT = 'a certificate client needs a clientAuthentication strategy';
+/**
+ * Whether a client row's refusal gets the hint: no strategy, and no client
+ * at all — the key store answered none, or one without a client id. A
+ * client that lacks only its secret or its URL is a secret client with a
+ * gap, and gets 4.0.0's words alone. Decided from what was read, never by
+ * asking the store about a certificate.
+ */
+function noClientHint(clientAuthenticated, client) {
+    return !clientAuthenticated && !present(client?.uaaClientId);
+}
+/** A client row's refusal: 4.0.0's words, and the hint when `hinted`. */
+function clientRowError(destination, lacking, reason, hinted) {
+    return new DestinationConfigError_1.DestinationConfigError(destination, lacking, hinted ? `${reason}; ${CERTIFICATE_HINT}` : reason);
+}
+/** `clientAuthentication` for a provider's config: present only when given. */
+function authenticatedBy(clientAuthentication) {
+    return clientAuthentication ? { clientAuthentication } : {};
+}
 /** The names of the fields among `names` that `source` lacks or holds as `''`. */
 function missing(source, names) {
     return names.filter((name) => !present(source?.[name]));
@@ -94,30 +166,55 @@ function sncProvider(destination, means, logger) {
         throw new DestinationConfigError_1.DestinationConfigError(destination, ['sncPartnerName'], 'an snc destination needs the system’s SNC name');
     }
     try {
-        return auth_providers_1.SncLogonProvider.forSecureLoginClient({
+        return auth_providers_1.SncLogonProvider.forSecureLoginClient((0, contractShape_1.asContract)({
             partnerName: means.sncPartnerName,
             qop: present(means.sncQop) ? means.sncQop : undefined,
             sncLib: present(means.sncLib) ? means.sncLib : undefined,
             myName: present(means.sncMyName) ? means.sncMyName : undefined,
             logger,
-        });
+        }));
     }
-    catch (error) {
-        if (error instanceof auth_providers_1.ValidationError) {
-            throw new DestinationConfigError_1.DestinationConfigError(destination, (error.missingFields ?? []).map((field) => SNC_FIELDS[field] ?? field), 'the SNC provider refused the destination’s SNC settings');
-        }
-        throw error;
+    catch (thrown) {
+        // Decided by kind, read through auth-errors — never by class: a failure
+        // of another installed copy of auth-errors reads the same.
+        const error = (0, auth_errors_1.readFailure)(thrown, 'resolving-snc-library');
+        const fields = error.kind === 'configuration'
+            ? mappedFields(error.facts.fields, SNC_FIELDS)
+            : SNC_STORE_FIELDS.filter((field) => present(means[field]));
+        throw new DestinationConfigError_1.DestinationConfigError(destination, fields, 'the SNC provider refused the destination’s SNC settings', error);
+    }
+}
+/** The four SNC fields of the means, in the order a refusal names them. */
+const SNC_STORE_FIELDS = [
+    'sncPartnerName',
+    'sncQop',
+    'sncLib',
+    'sncMyName',
+];
+/**
+ * A provider's configuration field names as the store's (or the broker's
+ * option names), through a row's map; a name the map does not hold is kept —
+ * it is one of interfaces-auth's `CONFIG_FIELDS`, a name, never a value.
+ */
+function mappedFields(fields, map) {
+    const names = [];
+    for (const field of fields) {
+        const name = map[field] ?? field;
+        if (!names.includes(name))
+            names.push(name);
     }
+    return names;
 }
 /**
  * `none` → the credential handed over, from the session: the only way in, so
  * required. Read from the secret alone — the means are not a seed.
  *
  * The broker did not obtain it and cannot obtain it again, so a binding that
- * does not match is refused, never discarded: `issuedFor`
- * must always equal the destination's resource — it is what stops the
- * credential going to another one; `issuedBy` is compared only when the means
- * state an issuer.
+ * does not match is refused, never discarded: `issuedFor` must equal the
+ * destination's resource — it is what stops the credential going to another
+ * one — and `issuedBy` must be exactly the row's record: a credential
+ * handed over with a 4.x binding, or none, is refused until it is written
+ * again with 5.0.0's `bindingOf`.
  */
 function handedOverProvider(destination, authType, secret, binding) {
     const credential = authType === 'jwt' ? secret?.authorizationToken : secret?.sessionCookies;
@@ -129,9 +226,8 @@ function handedOverProvider(destination, authType, secret, binding) {
     const unbound = [];
     if (!(0, binding_1.sameResource)(secret, binding))
         unbound.push('issuedFor');
-    if (binding.issuerStated && !(0, binding_1.sameIssuer)(secret, binding)) {
+    if (!(0, binding_1.sameRecord)(secret, binding))
         unbound.push('issuedBy');
-    }
     if (unbound.length > 0) {
         throw new DestinationConfigError_1.DestinationConfigError(destination, unbound, 'the credential in the session is not bound to this destination’s means');
     }
@@ -139,77 +235,218 @@ function handedOverProvider(destination, authType, secret, binding) {
         ? auth_providers_1.TokenAuthProvider.fixed(credential)
         : new auth_providers_1.SamlAuthProvider(credential);
 }
+/** `onWriteFailure` as given: `'fail'` or `'continue'`, nothing else. */
+function isWriteFailurePolicy(value) {
+    return value === 'fail' || value === 'continue';
+}
+/**
+ * The consumer options a token row lacks, by name: `renewal` when it is no
+ * function, `onWriteFailure` when it is neither `'fail'` nor `'continue'`.
+ * There is no default for either.
+ */
+function optionsLacking(options) {
+    const lacking = [];
+    if (typeof options.renewal !== 'function')
+        lacking.push('renewal');
+    if (!isWriteFailurePolicy(options.onWriteFailure)) {
+        lacking.push('onWriteFailure');
+    }
+    return lacking;
+}
+/**
+ * The row's renewal strategy: `renewal(destination, grant)`, called once per
+ * build after every other check has passed. A throw is refused naming
+ * `renewal`, carrying what it threw as auth-errors reads it.
+ */
+function renewalFor(destination, grant, renewal) {
+    try {
+        // Checked by optionsLacking before any row gets here.
+        return renewal(destination, grant);
+    }
+    catch (thrown) {
+        throw new DestinationConfigError_1.DestinationConfigError(destination, ['renewal'], 'the renewal option failed', (0, auth_errors_1.readFailure)(thrown, 'renewal-strategy'));
+    }
+}
+/**
+ * The row's persistence: auth-providers' `refreshStatePersistence` over the
+ * broker's write, with the consumer's `onWriteFailure` as given.
+ */
+function persistenceFor(options) {
+    return (0, auth_providers_1.refreshStatePersistence)(options.write, (0, contractShape_1.asContract)({
+        // Checked by optionsLacking before any row gets here.
+        onWriteFailure: options.onWriteFailure,
+        // No logger: the broker's writer logs every failed write once, naming
+        // the destination; the persistence's own line would repeat it.
+    }));
+}
+/**
+ * Builds the provider — the persistence strategy and the constructor —
+ * inside one guard: a refusal of the configuration the row gave it is a
+ * `DestinationConfigError` naming the store fields (or broker options) its
+ * facts name, through the row's field map, carrying the provider's error.
+ */
+function constructed(destination, fieldMap, build) {
+    try {
+        return build();
+    }
+    catch (thrown) {
+        const error = (0, auth_errors_1.readFailure)(thrown, 'unfamiliar-error');
+        throw new DestinationConfigError_1.DestinationConfigError(destination, error.kind === 'configuration'
+            ? mappedFields(error.facts.fields, fieldMap)
+            : [], 'the provider refused the configuration the destination states', error);
+    }
+}
+/** The fields every token row's provider shares, as the store and the broker name them. */
+const COMMON_FIELDS = {
+    clientId: 'uaaClientId',
+    clientSecret: 'uaaClientSecret',
+    uaaUrl: 'uaaUrl',
+    renewal: 'renewal',
+    persistence: 'onWriteFailure',
+    onWriteFailure: 'onWriteFailure',
+    authorization: 'authorization',
+    clientAuthentication: 'clientAuthentication',
+};
+const OIDC_FIELDS = {
+    ...COMMON_FIELDS,
+    issuerUrl: 'oidcIssuerUrl',
+    tokenEndpoint: 'oidcTokenEndpoint',
+    authorizationEndpoint: 'oidcAuthorizationEndpoint',
+    deviceAuthorizationEndpoint: 'oidcDeviceAuthorizationEndpoint',
+    scopes: 'oidcScopes',
+    scope: 'oidcScopes',
+    audience: 'oidcAudience',
+    subjectToken: 'oidcSubjectToken',
+    subjectTokenType: 'oidcSubjectTokenType',
+    actorToken: 'oidcActorToken',
+    actorTokenType: 'oidcActorTokenType',
+    authorization: 'oidcAuthorization',
+    presenter: 'deviceCodePresenter',
+};
+const SAML_FIELDS = {
+    ...COMMON_FIELDS,
+    idpSsoUrl: 'samlIdpSsoUrl',
+    spEntityId: 'samlSpEntityId',
+    acsUrl: 'samlAcsUrl',
+    relayState: 'samlRelayState',
+    idpEntityId: 'samlIdpEntityId',
+    idpInitiated: 'samlIdpInitiated',
+    idpCertificates: 'samlIdpCertificates',
+    assertionValidator: 'samlIdpCertificates',
+    clockSkewMs: 'samlClockSkewMs',
+    tokenUrl: 'samlTokenUrl',
+    cookieProvider: 'samlCookies',
+};
 function isUaaGrant(grant) {
     return (grant === 'authorization_code' ||
         grant === 'client_credentials' ||
         grant === 'passcode');
 }
 /**
- * `jwt` / `authorization_code` → `AuthorizationCodeProvider`,
- * `client_credentials` → `ClientCredentialsProvider`, `passcode` →
- * `UaaPasscodeProvider`: the client from the key store, the seed from the
- * session (not for `client_credentials`, whose row takes the client alone).
- *
- * Every field and option the row lacks is named in one error, before the
- * consumer's `authorization` is called. `serviceUrl` is not among them: the
- * providers read the client and `uaaUrl` only. `uaaClientSecret: ''` is a public
- * client: `passcode` takes it as no secret; the other two rows' providers
- * require a secret, so for them `''` is missing.
+ * Every field and option a UAA row lacks, named in one error — or nothing.
+ * `serviceUrl` is not among them: the providers read the client and `uaaUrl`
+ * only. Without a strategy, `uaaClientSecret: ''` is a public client:
+ * `passcode` takes it as no secret; the other two rows' providers require a
+ * secret, so for them `''` is missing.
  */
-function uaaProvider(row) {
-    const { destination, grant, client, secret } = row;
+function uaaRefusal(check) {
+    const { destination, grant, client, clientAuthenticated } = check;
     const lacking = [];
-    if (!present(client?.uaaUrl))
-        lacking.push('uaaUrl');
-    if (!present(client?.uaaClientId))
-        lacking.push('uaaClientId');
-    if (grant !== 'passcode' && !present(client?.uaaClientSecret)) {
+    if (client !== undefined) {
+        if (!present(client?.uaaUrl))
+            lacking.push('uaaUrl');
+        if (!present(client?.uaaClientId))
+            lacking.push('uaaClientId');
+    }
+    if (!clientAuthenticated &&
+        grant !== 'passcode' &&
+        !present(secretOf(client ?? null))) {
         lacking.push('uaaClientSecret');
     }
-    if (grant !== 'client_credentials' && !row.authorization) {
+    if (grant !== 'client_credentials' && !check.authorization) {
         lacking.push('authorization');
     }
-    if (lacking.length > 0) {
-        throw new DestinationConfigError_1.DestinationConfigError(destination, lacking, `a jwt destination with grantType ${grant} lacks what its grant needs`);
-    }
+    lacking.push(...optionsLacking(check));
+    if (lacking.length === 0)
+        return undefined;
+    return clientRowError(destination, lacking, `a jwt destination with grantType ${grant} lacks what its grant needs`, noClientHint(clientAuthenticated, client));
+}
+/**
+ * `jwt` / `authorization_code` → `AuthorizationCodeProvider`,
+ * `client_credentials` → `ClientCredentialsProvider`, `passcode` →
+ * `UaaPasscodeProvider`: the client from the key store, the seed from the
+ * session (not for `client_credentials`, whose row takes the client alone),
+ * the consumer's renewal for this grant, and the broker's persistence.
+ *
+ * Every field and option the row lacks is named in one error
+ * (`uaaRefusal`), before the consumer's `authorization` or `renewal` is
+ * called. On the strategy path the client may be a certificate client's
+ * identity, which holds no secret field at all (`RowClient`). With the
+ * strategy's answer (`clientAuthentication`) no secret is required and none
+ * is passed: the provider authenticates its client with the answer.
+ */
+function uaaProvider(row) {
+    const { destination, grant, client, secret, clientAuthentication } = row;
+    const refusal = uaaRefusal({
+        ...row,
+        clientAuthenticated: !!clientAuthentication,
+    });
+    if (refusal)
+        throw refusal;
     const uaaUrl = client?.uaaUrl;
     const clientId = client?.uaaClientId;
-    const clientSecret = present(client?.uaaClientSecret)
-        ? client.uaaClientSecret
+    const clientSecret = !clientAuthentication && present(secretOf(client))
+        ? secretOf(client)
         : undefined;
-    const hooks = { onTokens: row.onTokens };
+    const renewal = renewalFor(destination, grant, row.renewal);
+    const hooks = () => ({
+        renewal,
+        persistence: persistenceFor(row),
+        ...authenticatedBy(clientAuthentication),
+        authDebug: row.authDebug,
+    });
     if (grant === 'client_credentials') {
-        return new auth_providers_1.ClientCredentialsProvider({
-            uaaUrl,
-            clientId,
-            clientSecret: clientSecret,
-            logger: row.logger,
-            ...hooks,
-        });
+        // The client alone: no seed.
+        return {
+            provider: constructed(destination, COMMON_FIELDS, () => new auth_providers_1.ClientCredentialsProvider({
+                uaaUrl,
+                clientId,
+                ...(clientSecret === undefined ? {} : { clientSecret }),
+                logger: row.logger,
+                ...hooks(),
+            })),
+            seededRefreshToken: undefined,
+        };
     }
     const seed = tokenSeed(secret);
     // Checked above: the rows that reach here need it.
     const authorization = row.authorization(destination, grant);
     if (grant === 'authorization_code') {
-        return new auth_providers_1.AuthorizationCodeProvider({
+        return {
+            provider: constructed(destination, COMMON_FIELDS, () => new auth_providers_1.AuthorizationCodeProvider((0, contractShape_1.asContract)({
+                uaaUrl,
+                clientId,
+                ...(clientSecret === undefined ? {} : { clientSecret }),
+                authorization,
+                ...seed,
+                logger: row.logger,
+                ...hooks(),
+            }))),
+            seededRefreshToken: seed.refreshToken,
+        };
+    }
+    return {
+        provider: constructed(destination, COMMON_FIELDS, () => new auth_providers_1.UaaPasscodeProvider((0, contractShape_1.asContract)({
             uaaUrl,
             clientId,
-            clientSecret: clientSecret,
+            clientSecret,
             authorization,
             ...seed,
             logger: row.logger,
-            ...hooks,
-        });
-    }
-    return new auth_providers_1.UaaPasscodeProvider({
-        uaaUrl,
-        clientId,
-        clientSecret,
-        authorization,
-        ...seed,
-        logger: row.logger,
-        ...hooks,
-    });
+            ...hooks(),
+        }))),
+        seededRefreshToken: seed.refreshToken,
+    };
 }
 /** The seed of a token provider: the stored token, its refresh token and expiry. */
 function tokenSeed(secret) {
@@ -244,93 +481,161 @@ const OIDC_ENDPOINTS = {
     token_exchange: ['oidcTokenEndpoint'],
 };
 /**
- * `jwt` / `oidc_authorization_code` → `OidcBrowserProvider`, `device_code` →
- * `OidcDeviceFlowProvider`, `password` → `OidcPasswordProvider`,
- * `token_exchange` → `OidcTokenExchangeProvider`: the client id (and secret,
- * `''` being a public client) from the key store's client, the grant's data
- * from its `oidc*` fields, the seed from the session.
- *
+ * Every field and option an OIDC row lacks, named in one error — or nothing.
  * The endpoints: `oidcIssuerUrl`, from which the provider discovers them, or
  * every explicit endpoint the row uses — without either the error names the
- * issuer and the endpoints missing. Every field and option the row lacks is
- * named in one error, before any collaborator is called. `token_exchange`
- * takes one scope string: the stored scopes joined by a space.
+ * issuer and the endpoints missing.
  */
-function oidcProvider(row) {
-    const { destination, grant, means, client } = row;
+function oidcRefusal(check) {
+    const { destination, grant, means, client } = check;
     const lacking = [];
-    if (!present(client?.uaaClientId))
+    if (client !== undefined && !present(client?.uaaClientId)) {
         lacking.push('uaaClientId');
+    }
     if (!present(means.oidcIssuerUrl)) {
         const endpoints = OIDC_ENDPOINTS[grant].filter((name) => !present(means[name]));
         if (endpoints.length > 0)
             lacking.push('oidcIssuerUrl', ...endpoints);
     }
+    if (!trustShaped(means.oidcScopes, 'strings'))
+        lacking.push('oidcScopes');
     if (grant === 'password') {
         lacking.push(...missing(means, ['username', 'password']));
     }
     if (grant === 'token_exchange') {
         lacking.push(...missing(means, ['oidcSubjectToken', 'oidcSubjectTokenType']));
+        if (!trustShaped(means.oidcActorTokenType, 'string')) {
+            lacking.push('oidcActorTokenType');
+        }
     }
-    if (grant === 'oidc_authorization_code' && !row.oidcAuthorization) {
+    if (grant === 'oidc_authorization_code' && !check.oidcAuthorization) {
         lacking.push('oidcAuthorization');
     }
-    if (grant === 'device_code' && !row.deviceCodePresenter) {
+    if (grant === 'device_code' && !check.deviceCodePresenter) {
         lacking.push('deviceCodePresenter');
     }
-    if (lacking.length > 0) {
-        throw new DestinationConfigError_1.DestinationConfigError(destination, lacking, `a jwt destination with grantType ${grant} lacks what its grant needs`);
-    }
+    lacking.push(...optionsLacking(check));
+    if (lacking.length === 0)
+        return undefined;
+    return clientRowError(destination, lacking, `a jwt destination with grantType ${grant} lacks what its grant needs`, noClientHint(check.clientAuthenticated, client));
+}
+/**
+ * `jwt` / `oidc_authorization_code` → `OidcBrowserProvider`, `device_code` →
+ * `OidcDeviceFlowProvider`, `password` → `OidcPasswordProvider`,
+ * `token_exchange` → `OidcTokenExchangeProvider`: the client id (and secret,
+ * `''` being a public client) from the key store's client, the grant's data
+ * from its `oidc*` fields, the seed from the session, the consumer's renewal
+ * for this grant, and the broker's persistence.
+ *
+ * Every field and option the row lacks is named in one error
+ * (`oidcRefusal`), before any collaborator is called. `token_exchange` takes
+ * one scope string: the stored scopes joined by a space.
+ */
+function oidcProvider(row) {
+    const { destination, grant, means, client } = row;
+    const refusal = oidcRefusal({
+        ...row,
+        clientAuthenticated: !!row.clientAuthentication,
+    });
+    if (refusal)
+        throw refusal;
     const scopes = Array.isArray(means.oidcScopes) && means.oidcScopes.length > 0
         ? means.oidcScopes
         : undefined;
-    const common = {
+    const renewal = renewalFor(destination, grant, row.renewal);
+    const seed = tokenSeed(row.secret);
+    const built = (provider) => ({
+        provider,
+        seededRefreshToken: seed.refreshToken,
+    });
+    const common = () => ({
         issuerUrl: stated(means.oidcIssuerUrl),
         clientId: client?.uaaClientId,
-        clientSecret: stated(client?.uaaClientSecret),
+        clientSecret: row.clientAuthentication
+            ? undefined
+            : stated(secretOf(client)),
+        ...authenticatedBy(row.clientAuthentication),
         tokenEndpoint: stated(means.oidcTokenEndpoint),
-        ...tokenSeed(row.secret),
+        ...seed,
         logger: row.logger,
-        onTokens: row.onTokens,
-    };
+        authDebug: row.authDebug,
+        renewal,
+        persistence: persistenceFor(row),
+    });
     switch (grant) {
-        case 'oidc_authorization_code':
-            return new auth_providers_1.OidcBrowserProvider({
-                ...common,
+        case 'oidc_authorization_code': {
+            // Checked above.
+            const authorization = row.oidcAuthorization(destination);
+            return built(constructed(destination, OIDC_FIELDS, () => new auth_providers_1.OidcBrowserProvider((0, contractShape_1.asContract)({
+                ...common(),
                 scopes,
                 authorizationEndpoint: stated(means.oidcAuthorizationEndpoint),
-                // Checked above.
-                authorization: row.oidcAuthorization(destination),
-            });
-        case 'device_code':
-            return new auth_providers_1.OidcDeviceFlowProvider({
-                ...common,
+                authorization,
+            }))));
+        }
+        case 'device_code': {
+            const presenter = row.deviceCodePresenter(destination);
+            return built(constructed(destination, OIDC_FIELDS, () => new auth_providers_1.OidcDeviceFlowProvider((0, contractShape_1.asContract)({
+                ...common(),
                 scopes,
                 deviceAuthorizationEndpoint: stated(means.oidcDeviceAuthorizationEndpoint),
-                presenter: row.deviceCodePresenter(destination),
-            });
+                presenter,
+            }))));
+        }
         case 'password':
-            return new auth_providers_1.OidcPasswordProvider({
-                ...common,
+            return built(constructed(destination, OIDC_FIELDS, () => new auth_providers_1.OidcPasswordProvider((0, contractShape_1.asContract)({
+                ...common(),
                 scopes,
                 username: means.username,
                 password: means.password,
-            });
+            }))));
         case 'token_exchange':
-            return new auth_providers_1.OidcTokenExchangeProvider({
-                ...common,
+            return built(constructed(destination, OIDC_FIELDS, () => new auth_providers_1.OidcTokenExchangeProvider((0, contractShape_1.asContract)({
+                ...common(),
                 scope: scopes?.join(' '),
                 subjectToken: means.oidcSubjectToken,
                 subjectTokenType: means.oidcSubjectTokenType,
                 audience: stated(means.oidcAudience),
                 actorToken: stated(means.oidcActorToken),
                 actorTokenType: stated(means.oidcActorTokenType),
-            });
+            }))));
     }
 }
 function isSamlGrant(grant) {
     return grant === 'saml2_pure' || grant === 'saml2_bearer';
 }
+/** Every field and option a SAML row lacks, named in one error — or nothing. */
+function samlRefusal(check) {
+    const { destination, grant, means, client } = check;
+    const lacking = missing(means, [
+        'samlIdpSsoUrl',
+        'samlSpEntityId',
+        'samlIdpEntityId',
+    ]);
+    const certificates = means.samlIdpCertificates;
+    if (!Array.isArray(certificates) ||
+        certificates.length === 0 ||
+        !certificates.every(present)) {
+        lacking.push('samlIdpCertificates');
+    }
+    if (!trustShaped(means.samlIdpInitiated, 'boolean')) {
+        lacking.push('samlIdpInitiated');
+    }
+    if (grant === 'saml2_bearer' && client !== undefined) {
+        lacking.push(...missing(client, ['uaaUrl', 'uaaClientId']));
+    }
+    if (!check.authorization)
+        lacking.push('authorization');
+    if (grant === 'saml2_pure' && !check.samlCookies) {
+        lacking.push('samlCookies');
+    }
+    if (!check.assertionReplayStore)
+        lacking.push('assertionReplayStore');
+    lacking.push(...optionsLacking(check));
+    if (lacking.length === 0)
+        return undefined;
+    return clientRowError(destination, lacking, `a saml destination with grantType ${grant} lacks what its grant needs`, grant === 'saml2_bearer' && noClientHint(check.clientAuthenticated, client));
+}
 /**
  * `saml` / `saml2_pure` → `Saml2PureProvider`, `saml2_bearer` →
  * `Saml2BearerProvider`, each validating the assertion before anything uses
@@ -343,39 +648,26 @@ function isSamlGrant(grant) {
  *
  * `saml2_pure` is seeded with the stored cookies and `expiresAt`;
  * `saml2_bearer` with the stored token, its refresh token and expiry, and
- * takes the client (`uaaUrl`, `uaaClientId`; `uaaClientSecret` `''` a public
- * client) and `samlTokenUrl` when stated.
+ * takes the client (`uaaUrl`, `uaaClientId`; without a strategy,
+ * `uaaClientSecret` `''` a public client; on the strategy path the identity
+ * alone, no secret) and `samlTokenUrl` when stated. Both take the consumer's
+ * renewal for their grant and the broker's persistence.
  *
- * Every field and option the row lacks is named in one error, before any
- * collaborator is called; so is a `samlClockSkewMs` that is not a whole number
- * of milliseconds, and a certificate the validator cannot read — by name, never
- * the value.
+ * Every field and option the row lacks is named in one error
+ * (`samlRefusal`), before any collaborator is called; so is a
+ * `samlClockSkewMs` that is not a whole number of milliseconds, and a
+ * certificate the validator cannot read — by name, never the value, the
+ * validator's error carried.
  */
 function samlProvider(row) {
     const { destination, grant, means, client } = row;
-    const lacking = missing(means, [
-        'samlIdpSsoUrl',
-        'samlSpEntityId',
-        'samlIdpEntityId',
-    ]);
+    const refusal = samlRefusal({
+        ...row,
+        clientAuthenticated: !!row.clientAuthentication,
+    });
+    if (refusal)
+        throw refusal;
     const certificates = means.samlIdpCertificates;
-    if (!Array.isArray(certificates) ||
-        certificates.length === 0 ||
-        !certificates.every(present)) {
-        lacking.push('samlIdpCertificates');
-    }
-    if (grant === 'saml2_bearer') {
-        lacking.push(...missing(client, ['uaaUrl', 'uaaClientId']));
-    }
-    if (!row.authorization)
-        lacking.push('authorization');
-    if (grant === 'saml2_pure' && !row.samlCookies)
-        lacking.push('samlCookies');
-    if (!row.assertionReplayStore)
-        lacking.push('assertionReplayStore');
-    if (lacking.length > 0) {
-        throw new DestinationConfigError_1.DestinationConfigError(destination, lacking, `a saml destination with grantType ${grant} lacks what its grant needs`);
-    }
     const skew = means.samlClockSkewMs;
     if (skew !== undefined && !(Number.isInteger(skew) && skew >= 0)) {
         throw new DestinationConfigError_1.DestinationConfigError(destination, ['samlClockSkewMs'], 'samlClockSkewMs is not a whole, non-negative number of milliseconds');
@@ -386,18 +678,20 @@ function samlProvider(row) {
         : auth_providers_1.createSignedAssertionValidator;
     let assertionValidator;
     try {
-        assertionValidator = createValidator({
+        assertionValidator = createValidator((0, contractShape_1.asContract)({
             idpCertificates: certificates,
             clockSkewMs: skew,
             replayStore,
-        });
+        }));
     }
-    catch {
-        // The validator's own message may quote what it could not read; the
-        // error names the field only.
-        throw new DestinationConfigError_1.DestinationConfigError(destination, ['samlIdpCertificates'], 'a SAML signing certificate the destination states is not a valid X.509 certificate');
+    catch (thrown) {
+        // The field is named, never its value; the validator's error is carried
+        // as auth-errors reads it.
+        throw new DestinationConfigError_1.DestinationConfigError(destination, ['samlIdpCertificates'], 'a SAML signing certificate the destination states is not a valid X.509 certificate', (0, auth_errors_1.readFailure)(thrown, 'validating-assertion'));
     }
-    const common = {
+    const renewal = renewalFor(destination, grant, row.renewal);
+    const authorization = row.authorization(destination, grant);
+    const common = () => ({
         idpSsoUrl: means.samlIdpSsoUrl,
         spEntityId: means.samlSpEntityId,
         acsUrl: stated(means.samlAcsUrl),
@@ -405,25 +699,41 @@ function samlProvider(row) {
         idpEntityId: means.samlIdpEntityId,
         idpInitiated: means.samlIdpInitiated === true,
         assertionValidator,
-        authorization: row.authorization(destination, grant),
+        authorization,
         logger: row.logger,
-        onTokens: row.onTokens,
-    };
+        authDebug: row.authDebug,
+        renewal,
+        persistence: persistenceFor(row),
+    });
     if (grant === 'saml2_pure') {
         const secret = row.secret;
-        return new auth_providers_1.Saml2PureProvider({
-            ...common,
-            cookieProvider: row.samlCookies(destination),
-            accessToken: stated(secret?.sessionCookies),
-            expiresAt: typeof secret?.expiresAt === 'number' ? secret.expiresAt : undefined,
-        });
-    }
-    return new auth_providers_1.Saml2BearerProvider({
-        ...common,
-        tokenUrl: stated(means.samlTokenUrl),
-        uaaUrl: client?.uaaUrl,
-        clientId: client?.uaaClientId,
-        clientSecret: stated(client?.uaaClientSecret),
-        ...tokenSeed(row.secret),
-    });
+        const cookieProvider = row.samlCookies(destination);
+        // The cookies and their expiry: no refresh token.
+        return {
+            provider: constructed(destination, SAML_FIELDS, () => new auth_providers_1.Saml2PureProvider((0, contractShape_1.asContract)({
+                ...common(),
+                cookieProvider,
+                accessToken: stated(secret?.sessionCookies),
+                expiresAt: typeof secret?.expiresAt === 'number'
+                    ? secret.expiresAt
+                    : undefined,
+            }))),
+            seededRefreshToken: undefined,
+        };
+    }
+    const seed = tokenSeed(row.secret);
+    return {
+        provider: constructed(destination, SAML_FIELDS, () => new auth_providers_1.Saml2BearerProvider((0, contractShape_1.asContract)({
+            ...common(),
+            tokenUrl: stated(means.samlTokenUrl),
+            uaaUrl: client?.uaaUrl,
+            clientId: client?.uaaClientId,
+            clientSecret: row.clientAuthentication
+                ? undefined
+                : stated(secretOf(client)),
+            ...authenticatedBy(row.clientAuthentication),
+            ...seed,
+        }))),
+        seededRefreshToken: seed.refreshToken,
+    };
 }