@wildo-ai/external-connectors-models 1.1.11 → 1.1.13

package/dist/esm/protocols/rest-operations.external-connectors-models.schemas.js

@@ -43,6 +43,7 @@
  * OpenAPI document is ever read (a second mapper input), it feeds `ProviderRestOperation` like
  * every other source.
  */
+import { ExternalProvider_Connection_OwnerScope } from '../core/security.external-connectors-models.schemas.js';
 /** @wildo_source:part:start external-connectors.models.rest-operation-contract facet:layer:shared facet:family:provider facet:audience:app-developer */
 /** Where a declared parameter rides on the wire. */
 export var ProviderRestParameterLocation;
@@ -109,6 +110,129 @@ export var ProviderRestPaginationStyle;
     /** The vendor returns its own continuation URL (`@odata.nextLink`, `links.next`). */
     ProviderRestPaginationStyle["LINK"] = "link";
 })(ProviderRestPaginationStyle || (ProviderRestPaginationStyle = {}));
+/**
+ * The schema a dot path into an operation's input names, or `undefined` when a segment names no declared field (#3399).
+ *
+ * Walked through Zod's own definition (`_zod.def`), not `instanceof`: a provider module may be built against another
+ * copy of Zod than the host's. Wrappers that leave the value's shape alone (optional, nullable, default, prefault,
+ * readonly, catch, nonoptional, a pipe's input, a lazy getter) are seen through. A union names the field when any of its
+ * options declares it, as a discriminated body does. Only an object's DECLARED fields count: a loose object admits other
+ * keys at runtime, and a picker for a key nobody declared is the typo this check exists to refuse.
+ */
+function providerRestInputSchemaAtPath(schema, segments) {
+    let current = schema;
+    for (let depth = 0; depth < 64; depth += 1) {
+        const def = current?._zod?.def;
+        if (def === undefined)
+            return undefined;
+        switch (def.type) {
+            case 'optional':
+            case 'nullable':
+            case 'default':
+            case 'prefault':
+            case 'readonly':
+            case 'catch':
+            case 'nonoptional':
+                current = def.innerType;
+                continue;
+            case 'pipe':
+                current = def.in;
+                continue;
+            case 'lazy':
+                current = typeof def.getter === 'function' ? def.getter() : undefined;
+                continue;
+            case 'union': {
+                if (segments.length === 0)
+                    return current;
+                const options = Array.isArray(def.options) ? def.options : [];
+                return options.map((option) => providerRestInputSchemaAtPath(option, segments)).find((found) => found !== undefined);
+            }
+            case 'object': {
+                if (segments.length === 0)
+                    return current;
+                const shape = def.shape;
+                const [head, ...rest] = segments;
+                if (shape === undefined || head === undefined || !Object.hasOwn(shape, head))
+                    return undefined;
+                return providerRestInputSchemaAtPath(shape[head], rest);
+            }
+            default:
+                return segments.length === 0 ? current : undefined;
+        }
+    }
+    return undefined;
+}
+/**
+ * Why an operation's `inputOptions` cannot be honoured, or an empty list (#3399). Each key, and each `dependsOn` value,
+ * is a dot path into the operation's input (`project.key`, `CustomerRef.value`; a top-level field is a one-segment
+ * path), and must name a field the operation's `inputSchema` declares. Checked where a catalogue loads (the operation
+ * executor, an augmentation or supplement merge) and at publish, so a mistyped path is refused once, by name, instead of
+ * offering a picker that fills nothing. An operation without an `inputSchema` passes its input through unvalidated and
+ * declares no fields, so there is nothing to check its paths against; only their shape is.
+ */
+export function describeProviderRestOperationInputOptionsDefects(operation) {
+    const defects = [];
+    const check = (path, role) => {
+        const segments = path.split('.');
+        if (segments.some((segment) => segment.length === 0)) {
+            defects.push(`operation '${operation.operationId}': ${role} '${path}' is not a dot path of field names`);
+            return;
+        }
+        if (operation.inputSchema !== undefined && providerRestInputSchemaAtPath(operation.inputSchema, segments) === undefined) {
+            defects.push(`operation '${operation.operationId}': ${role} '${path}' names no field of its inputSchema`);
+        }
+    };
+    for (const [inputPath, declaration] of Object.entries(operation.inputOptions ?? {})) {
+        check(inputPath, 'the inputOptions key');
+        for (const sourcePath of Object.values(declaration.dependsOn ?? {}))
+            check(sourcePath, `the dependsOn of '${inputPath}'`);
+        for (const fixed of Object.keys(declaration.input ?? {})) {
+            if (Object.hasOwn(declaration.dependsOn ?? {}, fixed)) {
+                defects.push(`operation '${operation.operationId}': the options of '${inputPath}' both fix and forward '${fixed}'`);
+            }
+        }
+        for (const listPath of [declaration.itemsPath, ...Object.keys(declaration.itemWhere ?? {})]) {
+            if (listPath !== undefined && listPath.split('.').some((segment) => segment.length === 0)) {
+                defects.push(`operation '${operation.operationId}': the options of '${inputPath}' name '${listPath}', which is not a dot path`);
+            }
+        }
+    }
+    return defects;
+}
+/**
+ * Why an operation's {@link ProviderRestOperationParameter.connectionFact} parameters cannot be honoured, or an empty
+ * list (#3397). Each must be a PATH parameter the path template uses, fed by nothing else (no `from`, `constantValue` or
+ * `multiSegment`), and the operation's `inputSchema` must not declare a field of its name: a caller is never asked for a
+ * value the connection supplies, and one it sends anyway is refused at the call. With `reportedAccountFacts` (the
+ * connection's OAuth2 declaration), each named fact must also be declared there with a `pathSegmentPattern`; without
+ * it the request compiler refuses the call, so a module walk passes them to catch it before any call.
+ */
+export function describeProviderRestOperationConnectionFactDefects(operation, reportedAccountFacts) {
+    const defects = [];
+    for (const parameter of operation.parameters ?? []) {
+        const factName = parameter.connectionFact;
+        if (factName === undefined)
+            continue;
+        const at = `operation '${operation.operationId}': the parameter '${parameter.name}' filled from the connection fact '${factName}'`;
+        if (parameter.in !== ProviderRestParameterLocation.PATH)
+            defects.push(`${at} is a ${parameter.in} parameter; only a PATH value may come from a connection fact`);
+        if (parameter.from !== undefined || parameter.constantValue !== undefined || parameter.multiSegment !== undefined) {
+            defects.push(`${at} also declares from, constantValue or multiSegment; its value comes from the connection alone`);
+        }
+        if (!operation.pathTemplate.includes(`{${parameter.name}}`))
+            defects.push(`${at} fills no '{${parameter.name}}' token of the path template`);
+        if (operation.inputSchema !== undefined && providerRestInputSchemaAtPath(operation.inputSchema, [parameter.name]) !== undefined) {
+            defects.push(`${at} is also declared by the inputSchema, which would ask callers for a value the connection supplies`);
+        }
+        if (reportedAccountFacts !== undefined) {
+            const fact = Object.hasOwn(reportedAccountFacts, factName) ? reportedAccountFacts[factName] : undefined;
+            if (fact?.pathSegmentPattern === undefined) {
+                defects.push(`${at}: the connection's OAuth2 contract declares no reported fact '${factName}' with a pathSegmentPattern`);
+            }
+        }
+    }
+    return defects;
+}
 /** What a successful HTTP answer said about the call, read through a {@link ProviderRestApplicationOutcome}. */
 export var ProviderRestApplicationOutcomeKind;
 (function (ProviderRestApplicationOutcomeKind) {
@@ -151,6 +275,22 @@ export function describeProviderRestApplicationOutcomeDefects(outcome) {
 export const PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER = '{tenant}';
 /** A tenant value the token URL admits: a GUID or a DNS name. Nothing that can leave the URL's path segment. */
 export const PROVIDER_CLIENT_CREDENTIALS_TENANT_SHAPE = /^[A-Za-z0-9](?:[A-Za-z0-9.-]{0,251}[A-Za-z0-9])?$/;
+/**
+ * The placeholder that BEGINS a client-credentials token URL whose token endpoint is on the deployment's own vendor
+ * instance (#3402): `{deploymentOrigin}/oauth2/v1/token`. Filled with the ORIGIN of the base URL the engine resolved for
+ * the REST contract (from `baseUrlHostEnvVarName` or `baseUrlEnvVarName`), never from a connection or a request.
+ *
+ * Okta is the case: every org has its own host (`<org>.okta.com`, or a custom domain), and its org authorization server's
+ * token endpoint is on that host. A fixed {@link ProviderRestClientCredentials.tokenHosts} list cannot admit a host only
+ * the operator knows, and a `{tenant}` value would be a second, separately typed copy of the host the operations already
+ * go to, which could disagree with it. Filling the token endpoint from the SAME resolved origin keeps them one value: the
+ * client's assertion is sent to the host the operator named, and to nothing a person connecting could choose.
+ *
+ * spec-cite: Okta Developer, "Implement OAuth for Okta with a service app"
+ * (https://developer.okta.com/docs/guides/implement-oauth-for-okta-serviceapp/main/, fetched 2026-11-10) — the token
+ * request is `POST https://{yourOktaDomain}/oauth2/v1/token`, and the assertion's `aud` is that URL.
+ */
+export const PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER = '{deploymentOrigin}';
 /** What a {@link ProviderClientCredentialsVerifiedFact} records: a value the person typed and the vendor accepted. */
 export var ProviderClientCredentialsFactSource;
 (function (ProviderClientCredentialsFactSource) {
@@ -159,6 +299,90 @@ export var ProviderClientCredentialsFactSource;
     /** The tenant whose token endpoint issued it. */
     ProviderClientCredentialsFactSource["TENANT"] = "tenant";
 })(ProviderClientCredentialsFactSource || (ProviderClientCredentialsFactSource = {}));
+/**
+ * The `grant_type` a client-credentials token request sends. Narrower than `OAuth2_GrantType` on purpose: these are the
+ * grants the client-credentials minter performs, each with nothing but the client's own credential and the declared
+ * parameters, and a member joins in the change that implements it.
+ */
+export var ProviderClientCredentialsGrantType;
+(function (ProviderClientCredentialsGrantType) {
+    /**
+     * The OAuth 2.0 client-credentials grant: the default.
+     * spec-cite: RFC 6749 §4.4.2 — `grant_type`: "REQUIRED. Value MUST be set to "client_credentials"." Fetched 2026-10-06.
+     */
+    ProviderClientCredentialsGrantType["CLIENT_CREDENTIALS"] = "client_credentials";
+    /**
+     * Zoom's server-to-server OAuth: the same exchange (a client authenticated with Basic, one token back, no refresh
+     * token) under Zoom's own grant name, with the account named in `account_id`.
+     * spec-cite: https://developers.zoom.us/docs/internal-apps/s2s-oauth/ — "Use the `account_credentials` grant type to
+     * generate an access token."; "Set up the body of the access token request using the `account_credentials`
+     * `grant_type` and your `account_id`." Fetched 2026-11-09.
+     */
+    ProviderClientCredentialsGrantType["ACCOUNT_CREDENTIALS"] = "account_credentials";
+})(ProviderClientCredentialsGrantType || (ProviderClientCredentialsGrantType = {}));
+/**
+ * The algorithms a client assertion is signed with (#3402). The JWS names (RFC 7518 §3.1) of the two asymmetric
+ * families every vendor measured accepts: Okta lists "RS256, RS384, RS512, ES256, ES384, and ES512" for a service app's
+ * key. A member joins when a vendor needs it.
+ * spec-cite: RFC 7518 §3.1 — "RS256 | RSASSA-PKCS1-v1_5 using SHA-256" and "ES256 | ECDSA using P-256 and SHA-256";
+ * https://developer.okta.com/docs/guides/implement-oauth-for-okta-serviceapp/main/ — the supported algorithms. Both
+ * fetched 2026-11-09.
+ */
+export var ProviderClientAssertionSigningAlgorithm;
+(function (ProviderClientAssertionSigningAlgorithm) {
+    /** ECDSA on P-256 with SHA-256: a short key and signature, and the default to choose for a new key. */
+    ProviderClientAssertionSigningAlgorithm["ES256"] = "ES256";
+    /** RSASSA-PKCS1-v1_5 with SHA-256, for a vendor or key store that issues RSA keys. */
+    ProviderClientAssertionSigningAlgorithm["RS256"] = "RS256";
+})(ProviderClientAssertionSigningAlgorithm || (ProviderClientAssertionSigningAlgorithm = {}));
+/** The longest a client assertion may live: Okta refuses one whose `exp` is more than an hour away. */
+export const PROVIDER_CLIENT_ASSERTION_MAXIMUM_LIFETIME_SECONDS = 3600;
+/** How long a client assertion lives when the declaration says nothing: long enough for one request, and no more. */
+export const PROVIDER_CLIENT_ASSERTION_DEFAULT_LIFETIME_SECONDS = 300;
+/**
+ * The slot of a client-credentials declaration's own CREDENTIAL: the client secret, or the private key (#3402).
+ * `undefined` only for a declaration {@link describeProviderRestClientCredentialsDefects} refuses.
+ */
+export function providerClientCredentialsCredentialSlot(credentials) {
+    return credentials.clientSecretSecretRef ?? credentials.privateKeyJwt?.privateKeySecretRef;
+}
+/**
+ * The parameter names {@link ProviderRestClientCredentials.tokenRequestParameters} may not declare: each is written by
+ * the grant itself (the grant type, the client's credential, the scope, a client assertion), so a second value would
+ * either be ignored or override the declared one.
+ */
+export const PROVIDER_CLIENT_CREDENTIALS_RESERVED_PARAMETER_NAMES = [
+    'grant_type', 'client_id', 'client_secret', 'scope', 'client_assertion', 'client_assertion_type',
+];
+/**
+ * Whether the client-credentials door of a REST contract serves a connection of this owner scope (#3398).
+ *
+ * Alone, it serves every admitted connection: the application's own (from its environment) and an organization's (from
+ * the credential the organization typed, as a Teams bot). Beside `oauth2`, a person or an organization connects through
+ * the authorization-code exchange, and the client-credentials grant serves the APPLICATION's own account only, so that
+ * account renews itself instead of resting on a pasted token that expires within the hour.
+ */
+export function providerClientCredentialsServesOwnerScope(contract, ownerScope) {
+    if (contract.clientCredentials === undefined)
+        return false;
+    return contract.oauth2 === undefined || ownerScope === ExternalProvider_Connection_OwnerScope.APPLICATION;
+}
+/**
+ * The slot a connection of this owner scope AUTHENTICATES with, as the engine's REST access resolver reads it: the
+ * client-credentials grant's own credential (its client secret or private key) when that door serves the owner scope
+ * ({@link providerClientCredentialsServesOwnerScope}), else `apiKey.secretRef`, the stored or pasted token itself.
+ *
+ * For a contract declaring `clientCredentials` beside `oauth2` (Box, Zoom, #3398) the two differ by owner: the
+ * application's own account mints from the server app's secret, while a person's connection reads its exchanged token
+ * from `apiKey.secretRef`. A tool standing in for one connection (`wildo providers probe`, `connect`, the doctor's
+ * configuration checks, all APPLICATION-owned) asks this instead of reading `apiKey.secretRef`, so it reads the slot the
+ * engine would. `undefined` when the contract names neither.
+ */
+export function providerRestConnectionCredentialSlot(contract, ownerScope) {
+    return providerClientCredentialsServesOwnerScope(contract, ownerScope)
+        ? providerClientCredentialsCredentialSlot(contract.clientCredentials)
+        : contract.apiKey?.secretRef;
+}
 /**
  * Why a client-credentials declaration cannot be honoured, or an empty list. Checked where a provider is composed:
  * a token URL that is not https, a token host that is not a DNS name or that the URL is not on, a tenant placeholder
@@ -167,9 +391,19 @@ export var ProviderClientCredentialsFactSource;
 export function describeProviderRestClientCredentialsDefects(credentials) {
     const defects = [];
     const hasTenant = credentials.tokenUrl.includes(PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER);
-    const filled = credentials.tokenUrl.split(PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER).join('tenant.example');
+    // The deployment's origin forms the WHOLE origin or nothing (#3402): text before it, or anything but a path after it,
+    // would compose a host the operator never named.
+    const onDeploymentOrigin = credentials.tokenUrl.includes(PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER);
+    if (onDeploymentOrigin && !credentials.tokenUrl.startsWith(`${PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER}/`)) {
+        defects.push(`clientCredentials.tokenUrl carries ${PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER} other than as its whole origin, followed by a path`);
+    }
+    if (onDeploymentOrigin && hasTenant)
+        defects.push(`clientCredentials.tokenUrl carries both ${PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER} and ${PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER}; the token endpoint has one source`);
+    const filled = credentials.tokenUrl
+        .split(PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER).join('tenant.example')
+        .split(PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER).join('https://deployment.example');
     if (/[{}]/.test(filled))
-        defects.push(`clientCredentials.tokenUrl '${credentials.tokenUrl}' carries a placeholder other than ${PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER}`);
+        defects.push(`clientCredentials.tokenUrl '${credentials.tokenUrl}' carries a placeholder other than ${PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER} and ${PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER}`);
     if (hasTenant && credentials.tenantSecretRef === undefined)
         defects.push(`clientCredentials.tokenUrl carries ${PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER} and no tenantSecretRef fills it`);
     if (!hasTenant && credentials.tenantSecretRef !== undefined)
@@ -177,17 +411,66 @@ export function describeProviderRestClientCredentialsDefects(credentials) {
     const host = /^https:\/\/([^/:?#]+)(?::\d+)?\//.exec(filled)?.[1]?.toLowerCase();
     if (host === undefined)
         defects.push(`clientCredentials.tokenUrl '${credentials.tokenUrl}' is not an https URL with a path`);
-    if (credentials.tokenHosts.length === 0)
-        defects.push('clientCredentials.tokenHosts admits no host');
-    for (const tokenHost of credentials.tokenHosts) {
-        if (!PROVIDER_OAUTH2_DNS_NAME_PATTERN.test(tokenHost.toLowerCase()))
-            defects.push(`clientCredentials.tokenHosts names '${tokenHost}', which is not a DNS name`);
+    if (onDeploymentOrigin) {
+        // The host is the deployment's, admitted where the engine resolves the operations' base URL; a fixed list would be
+        // a second, unchecked statement of it.
+        if (credentials.tokenHosts.length > 0)
+            defects.push(`clientCredentials.tokenHosts names hosts beside ${PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER}; the token host is the deployment's, so declare none`);
+    }
+    else {
+        if (credentials.tokenHosts.length === 0)
+            defects.push('clientCredentials.tokenHosts admits no host');
+        for (const tokenHost of credentials.tokenHosts) {
+            if (!PROVIDER_OAUTH2_DNS_NAME_PATTERN.test(tokenHost.toLowerCase()))
+                defects.push(`clientCredentials.tokenHosts names '${tokenHost}', which is not a DNS name`);
+        }
+        if (host !== undefined && !credentials.tokenHosts.some((tokenHost) => tokenHost.toLowerCase() === host)) {
+            defects.push(`clientCredentials.tokenUrl is on '${host}', which tokenHosts does not admit`);
+        }
+    }
+    if (credentials.scope !== undefined && credentials.scope.trim() === '')
+        defects.push('clientCredentials.scope is empty; omit it to send none');
+    const grantTypes = Object.values(ProviderClientCredentialsGrantType);
+    if (credentials.grantType !== undefined && !grantTypes.includes(credentials.grantType)) {
+        defects.push(`clientCredentials.grantType ${JSON.stringify(credentials.grantType)} is none of ${grantTypes.join(', ')}`);
     }
-    if (host !== undefined && !credentials.tokenHosts.some((tokenHost) => tokenHost.toLowerCase() === host)) {
-        defects.push(`clientCredentials.tokenUrl is on '${host}', which tokenHosts does not admit`);
+    // One credential: a secret or a private key (#3402), and the method agrees with which.
+    if ((credentials.clientSecretSecretRef === undefined) === (credentials.privateKeyJwt === undefined)) {
+        defects.push('clientCredentials declares exactly one of clientSecretSecretRef and privateKeyJwt');
+    }
+    const methods = credentials.privateKeyJwt !== undefined
+        ? [ProviderOAuth2ClientAuthenticationMethod.PRIVATE_KEY_JWT]
+        : [ProviderOAuth2ClientAuthenticationMethod.CLIENT_SECRET_POST, ProviderOAuth2ClientAuthenticationMethod.CLIENT_SECRET_BASIC];
+    if (credentials.tokenEndpointAuthMethod !== undefined && !methods.includes(credentials.tokenEndpointAuthMethod)) {
+        defects.push(`clientCredentials.tokenEndpointAuthMethod ${JSON.stringify(credentials.tokenEndpointAuthMethod)} is none of ${methods.join(', ')} for ${credentials.privateKeyJwt !== undefined ? 'a private key' : 'a client secret'}`);
+    }
+    if (credentials.privateKeyJwt !== undefined) {
+        const { privateKeySecretRef, algorithm, keyIdSecretRef, assertionLifetimeSeconds } = credentials.privateKeyJwt;
+        const algorithms = Object.values(ProviderClientAssertionSigningAlgorithm);
+        if (privateKeySecretRef.trim() === '')
+            defects.push('clientCredentials.privateKeyJwt.privateKeySecretRef names no slot');
+        if (!algorithms.includes(algorithm))
+            defects.push(`clientCredentials.privateKeyJwt.algorithm ${JSON.stringify(algorithm)} is none of ${algorithms.join(', ')}`);
+        if (keyIdSecretRef !== undefined && keyIdSecretRef.trim() === '')
+            defects.push('clientCredentials.privateKeyJwt.keyIdSecretRef names no slot');
+        if (assertionLifetimeSeconds !== undefined
+            && !(Number.isInteger(assertionLifetimeSeconds) && assertionLifetimeSeconds > 0 && assertionLifetimeSeconds <= PROVIDER_CLIENT_ASSERTION_MAXIMUM_LIFETIME_SECONDS)) {
+            defects.push(`clientCredentials.privateKeyJwt.assertionLifetimeSeconds is not a whole number of seconds from 1 to ${PROVIDER_CLIENT_ASSERTION_MAXIMUM_LIFETIME_SECONDS}`);
+        }
+    }
+    for (const [name, parameter] of Object.entries(credentials.tokenRequestParameters ?? {})) {
+        if (!/^[A-Za-z][A-Za-z0-9_.-]{0,63}$/.test(name))
+            defects.push(`clientCredentials.tokenRequestParameters names '${name}', which is not a parameter name`);
+        if (PROVIDER_CLIENT_CREDENTIALS_RESERVED_PARAMETER_NAMES.includes(name)) {
+            defects.push(`clientCredentials.tokenRequestParameters names '${name}', which the grant itself sends; declare it in its own field`);
+        }
+        const hasValue = typeof parameter.value === 'string';
+        const hasSlot = typeof parameter.secretRef === 'string';
+        if (hasValue === hasSlot)
+            defects.push(`clientCredentials.tokenRequestParameters '${name}' must declare exactly one of value and secretRef`);
+        else if ((parameter.value ?? parameter.secretRef ?? '').trim() === '')
+            defects.push(`clientCredentials.tokenRequestParameters '${name}' is empty`);
     }
-    if (credentials.scope.trim() === '')
-        defects.push('clientCredentials.scope is empty');
     for (const [name, fact] of Object.entries(credentials.verifiedAccountFacts ?? {})) {
         if (!/^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(name))
             defects.push(`clientCredentials.verifiedAccountFacts names '${name}', which is not a fact name`);
@@ -200,6 +483,59 @@ export function describeProviderRestClientCredentialsDefects(credentials) {
     }
     return defects;
 }
+/**
+ * Why a REST contract's `clientCredentials` sits wrongly beside the contract's other authentication fields, or an empty
+ * list (#2663, #3398). Checked where a provider is composed, beside {@link describeProviderRestClientCredentialsDefects}.
+ *
+ * - beside `requestSigning`: two ways to authenticate one call;
+ * - alone, `apiKey.secretRef` must be the client secret's slot, the one whose absence means "not configured";
+ * - beside `oauth2` the grant serves the APPLICATION's own account only ({@link providerClientCredentialsServesOwnerScope}),
+ *   so the module must admit that connection; `apiKey.secretRef` names the exchanged tokens' slot and may not be the
+ *   client secret's (a person's token would be read from it); and `verifiedAccountFacts`, which only an organization's
+ *   connection records, would record nothing.
+ * - a token URL on {@link PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER} (#3402) needs a base URL the
+ *   DEPLOYMENT names (`baseUrlHostEnvVarName` or `baseUrlEnvVarName`), and may serve the APPLICATION's connection only:
+ *   the deployment's instance is the application's own (its Okta org), so an organization minting there would
+ *   authenticate against the application's vendor tenant, never its own.
+ */
+export function describeProviderRestClientCredentialsPlacementDefects(contract, admitsApplicationConnection, 
+/** Whether the module admits an ORGANIZATION or USER connection. Omitted, `false`. */
+admitsNonApplicationConnection = false) {
+    const credentials = contract.clientCredentials;
+    if (credentials === undefined)
+        return [];
+    const defects = [];
+    if (contract.requestSigning !== undefined) {
+        defects.push('declares clientCredentials beside requestSigning; a call authenticates one way');
+    }
+    if (credentials.tokenUrl.includes(PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER)) {
+        if (contract.baseUrlHostEnvVarName === undefined && contract.baseUrlEnvVarName === undefined) {
+            defects.push(`clientCredentials.tokenUrl is on ${PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER}, and the contract's base URL is not one the deployment names (baseUrlHostEnvVarName or baseUrlEnvVarName)`);
+        }
+        if (!admitsApplicationConnection) {
+            defects.push(`clientCredentials.tokenUrl is on ${PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER}, which serves the application's own connection only, and the module admits none`);
+        }
+        if (contract.oauth2 === undefined && admitsNonApplicationConnection) {
+            defects.push(`clientCredentials.tokenUrl is on ${PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER}, the application's own vendor instance, and the module admits an organization or user connection that would mint there`);
+        }
+    }
+    const credentialSlot = providerClientCredentialsCredentialSlot(credentials);
+    if (contract.oauth2 === undefined) {
+        if (contract.apiKey.secretRef !== credentialSlot) {
+            defects.push(`apiKey.secretRef '${contract.apiKey.secretRef}' is not the client's credential slot '${credentialSlot}' (its secret or private key); that is the slot whose absence means not configured`);
+        }
+        return defects;
+    }
+    if (!admitsApplicationConnection)
+        defects.push('declares clientCredentials beside oauth2 and admits no APPLICATION connection, the only one that grant serves');
+    if (contract.apiKey.secretRef === credentialSlot) {
+        defects.push(`apiKey.secretRef '${contract.apiKey.secretRef}' is the client-credentials secret or key; beside oauth2 it names the slot of the exchanged access tokens`);
+    }
+    if (credentials.verifiedAccountFacts !== undefined) {
+        defects.push('declares clientCredentials.verifiedAccountFacts beside oauth2; an organization connects through oauth2, so no client-credentials fact is ever recorded');
+    }
+    return defects;
+}
 function readDotPath(body, path) {
     let current = body;
     for (const segment of path.split('.')) {
@@ -350,17 +686,15 @@ export var ProviderOAuth2ScopeMeaning;
      */
     ProviderOAuth2ScopeMeaning["PERMISSION"] = "PERMISSION";
 })(ProviderOAuth2ScopeMeaning || (ProviderOAuth2ScopeMeaning = {}));
-/** Whether `host` is admitted by one audience's hosts: an exact value, or `<labels><suffix>` for a declared suffix. */
+/**
+ * Whether `host` is admitted by one audience's hosts: an exact value, or `<labels><suffix>` for a declared suffix, with
+ * no more labels than `hostSuffixMaxLabels` allows (#3640).
+ */
 export function providerOAuth2AudienceAdmitsHost(audience, host) {
     const candidate = host.toLowerCase();
     if (audience.hosts.values.some((value) => value.toLowerCase() === candidate))
         return true;
-    return (audience.hosts.hostSuffixes ?? []).some((suffix) => {
-        const lowered = suffix.toLowerCase();
-        if (!candidate.endsWith(lowered) || candidate.length === lowered.length)
-            return false;
-        return PROVIDER_OAUTH2_DNS_NAME_PATTERN.test(candidate.slice(0, candidate.length - lowered.length));
-    });
+    return (audience.hosts.hostSuffixes ?? []).some((suffix) => providerHostIsUnderSuffix(candidate, suffix, audience.hosts.hostSuffixMaxLabels));
 }
 /**
  * The ONE audience whose hosts admit `host`, or `undefined` when none does. The declaration guarantees at most one
@@ -527,6 +861,76 @@ export var ProviderOAuth2PkceSupport;
     /** The vendor refuses PKCE from a confidential client (Slack): neither is sent. */
     ProviderOAuth2PkceSupport["NOT_ACCEPTED"] = "NOT_ACCEPTED";
 })(ProviderOAuth2PkceSupport || (ProviderOAuth2PkceSupport = {}));
+/**
+ * How this application's client authenticates to a vendor's token and revocation endpoints. See
+ * {@link ProviderRestOAuth2.tokenEndpointAuthMethod}.
+ *
+ * The values are the names the "OAuth Token Endpoint Authentication Methods" registry gives these two methods, which
+ * is what OpenID Connect and dynamic client registration call `token_endpoint_auth_method`, so a vendor's discovery
+ * document (`token_endpoint_auth_methods_supported`) can be compared with a declaration by eye.
+ * spec-cite: RFC 7591 §2 — `token_endpoint_auth_method`: "client_secret_post": "The client uses the HTTP POST parameters
+ * as defined in OAuth 2.0, Section 2.3.1."; "client_secret_basic": "The client uses HTTP Basic as defined in OAuth 2.0,
+ * Section 2.3.1." Fetched 2026-11-06.
+ *
+ * Narrower than `OAuth2_TokenEndpoint_AuthMethod` on purpose: that vocabulary also names `client_secret_jwt` and
+ * `none`, which nothing here performs. `private_key_jwt` joined with #3402, performed by the client-credentials grant
+ * only; the connected-account exchange refuses it at startup. A member nothing honours would
+ * be a declaration that looks like a client-authentication choice and changes nothing, so each method joins this
+ * vocabulary in the change that implements it.
+ */
+export var ProviderOAuth2ClientAuthenticationMethod;
+(function (ProviderOAuth2ClientAuthenticationMethod) {
+    /**
+     * `client_id` and `client_secret` as parameters of the request body: the engine's behaviour when nothing is declared,
+     * and what most vendors' own documentation shows. RFC 6749 calls it "NOT RECOMMENDED", which is why a vendor that
+     * documents Basic declares {@link CLIENT_SECRET_BASIC} rather than being met with this.
+     * spec-cite: RFC 6749 §2.3.1 — sending the two parameters in the body "is NOT RECOMMENDED and SHOULD be limited to
+     * clients unable to directly utilize the HTTP Basic authentication scheme". Fetched 2026-11-06.
+     */
+    ProviderOAuth2ClientAuthenticationMethod["CLIENT_SECRET_POST"] = "client_secret_post";
+    /**
+     * `Authorization: Basic base64(client_id ":" client_secret)`, each half form-urlencoded BEFORE base64, and neither in
+     * the body: one credential on one channel. Every authorization server must accept it (Zoom, Notion and Intuit document
+     * it as their client authentication).
+     * spec-cite: RFC 6749 §2.3.1 — "The client identifier is encoded using the "application/x-www-form-urlencoded"
+     * encoding algorithm per Appendix B", and so is the password, before both become the Basic user-id and password; "The
+     * authorization server MUST support the HTTP Basic authentication scheme". Appendix B encodes UTF-8 first, so `£` is
+     * `%C2%A3` and a space is `+`. Fetched 2026-11-06.
+     */
+    ProviderOAuth2ClientAuthenticationMethod["CLIENT_SECRET_BASIC"] = "client_secret_basic";
+    /**
+     * A JWT the client signs with its own private key, sent as `client_assertion` (#3402). Performed by the
+     * client-credentials grant only ({@link ProviderRestClientCredentials.privateKeyJwt}); the connected-account exchange
+     * does not sign assertions, so `oauth2.tokenEndpointAuthMethod` refuses it at startup.
+     * spec-cite: OpenID Connect Core 1.0 §9 — `private_key_jwt`: "Clients that have registered a public key sign a JWT
+     * using that key." Fetched 2026-11-09 from https://openid.net/specs/openid-connect-core-1_0.html.
+     */
+    ProviderOAuth2ClientAuthenticationMethod["PRIVATE_KEY_JWT"] = "private_key_jwt";
+})(ProviderOAuth2ClientAuthenticationMethod || (ProviderOAuth2ClientAuthenticationMethod = {}));
+/**
+ * How the parameters of a request to a vendor's token or revocation endpoint are written in its body. See
+ * {@link ProviderRestOAuth2.tokenRequestBodyEncoding} and {@link ProviderRestOAuth2.revocationRequestBodyEncoding}.
+ *
+ * The parameters are the same in both encodings (`grant_type`, `code`, `refresh_token`, `token`, …); only their
+ * serialization and the `Content-Type` change.
+ */
+export var ProviderOAuth2RequestBodyEncoding;
+(function (ProviderOAuth2RequestBodyEncoding) {
+    /**
+     * `application/x-www-form-urlencoded`, which RFC 6749 and RFC 7009 specify: the default for both requests.
+     * spec-cite: RFC 6749 §4.1.3 (the client makes the token request "by sending the following parameters using the
+     * "application/x-www-form-urlencoded" format"; §6 does the same for a refresh), and RFC 7009 §2.1 (the revocation
+     * request uses "the "application/x-www-form-urlencoded" format in the HTTP request entity-body"). Fetched 2026-11-06.
+     */
+    ProviderOAuth2RequestBodyEncoding["FORM"] = "FORM";
+    /**
+     * `application/json`, an object whose members are the same parameters as string values. A deviation some vendors
+     * document: Notion's token endpoint takes only JSON, and Intuit's own client library revokes with a JSON body.
+     * spec-cite: https://developers.notion.com/docs/authorization — the token request's `Content-Type: application/json`,
+     * fetched 2026-11-06.
+     */
+    ProviderOAuth2RequestBodyEncoding["JSON"] = "JSON";
+})(ProviderOAuth2RequestBodyEncoding || (ProviderOAuth2RequestBodyEncoding = {}));
 /**
  * A `scope` list encoding that deviates from RFC 6749's space-delimited list, in either direction: the token answer
  * ({@link ProviderRestOAuth2.grantedScopesDelimiter}) or the authorize request ({@link ProviderRestOAuth2.authorizeScopesDelimiter}).
@@ -544,6 +948,87 @@ export var ProviderOAuth2ScopeListDelimiter;
      */
     ProviderOAuth2ScopeListDelimiter["COMMA"] = "COMMA";
 })(ProviderOAuth2ScopeListDelimiter || (ProviderOAuth2ScopeListDelimiter = {}));
+/**
+ * What makes a client-authentication declaration unusable (see {@link ProviderRestOAuth2.tokenEndpointAuthMethod}):
+ *
+ * - a method or an encoding outside its vocabulary. The request builder tests for the declared member, so an unknown
+ *   value (a misspelling in a module written without types) would silently fall back to the default and send the
+ *   secret the way the vendor said not to;
+ * - a revocation encoding with no revocation URL, a setting that changes nothing.
+ */
+export function describeProviderOAuth2ClientAuthenticationDefects(oauth2) {
+    const defects = [];
+    // The exchange signs no assertion: a key-based client (#3402) authenticates only on the client-credentials grant.
+    const methods = [ProviderOAuth2ClientAuthenticationMethod.CLIENT_SECRET_POST, ProviderOAuth2ClientAuthenticationMethod.CLIENT_SECRET_BASIC];
+    const encodings = Object.values(ProviderOAuth2RequestBodyEncoding);
+    if (oauth2.tokenEndpointAuthMethod !== undefined && !methods.includes(oauth2.tokenEndpointAuthMethod)) {
+        defects.push(`declares tokenEndpointAuthMethod ${JSON.stringify(oauth2.tokenEndpointAuthMethod)}, which is none of ${methods.join(', ')}`);
+    }
+    for (const [field, value] of [['tokenRequestBodyEncoding', oauth2.tokenRequestBodyEncoding], ['revocationRequestBodyEncoding', oauth2.revocationRequestBodyEncoding]]) {
+        if (value !== undefined && !encodings.includes(value))
+            defects.push(`declares ${field} ${JSON.stringify(value)}, which is none of ${encodings.join(', ')}`);
+    }
+    if (oauth2.revocationRequestBodyEncoding !== undefined && oauth2.rfc7009RevocationUrl === undefined) {
+        defects.push('declares revocationRequestBodyEncoding without rfc7009RevocationUrl, so no revocation request uses it');
+    }
+    return defects;
+}
+/**
+ * The parameter names the token request writes itself, which {@link ProviderRestOAuth2.codeExchangeParameters} may not
+ * name: the exchange's own parameters (RFC 6749 §4.1.3), the client's credentials (§2.3.1) and assertion (RFC 7523 §2.2),
+ * and the refresh's (§6). A declared value for one of them would change what the request IS.
+ * semantic-literal-boundary: OAuth2 wire parameter names, as RFC 6749 and RFC 7523 spell them.
+ */
+const PROVIDER_OAUTH2_ENGINE_WRITTEN_TOKEN_PARAMETERS = new Set([
+    'grant_type', 'code', 'redirect_uri', 'code_verifier', 'client_id', 'client_secret', 'client_assertion', 'client_assertion_type', 'refresh_token', 'scope',
+]);
+/** An OAuth2 error code's shape (RFC 6749 §5.2: `error` values are `%x20-21 / %x23-5B / %x5D-7E`, no space in practice). */
+const PROVIDER_OAUTH2_ERROR_CODE_SHAPE = /^[A-Za-z0-9_.:-]{1,128}$/;
+/** A token-request parameter name a declaration may add: a plain identifier, so it cannot smuggle structure into a body. */
+const PROVIDER_OAUTH2_EXTRA_PARAMETER_NAME = /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/;
+/**
+ * What makes a token-request declaration unusable (follow-up to #3392), checked where the provider registry composes:
+ *
+ * - a {@link ProviderRestOAuth2.codeExchangeParameters} name that is not a plain identifier, that names a parameter the
+ *   engine writes itself, or whose value is empty;
+ * - a {@link ProviderRestOAuth2.refreshRefusals} entry whose code is not code-shaped (it would never match), is
+ *   `invalid_grant` (already a refusal, so the entry says nothing) or `invalid_client` (the application's registration,
+ *   never one person's grant), or whose description is empty.
+ */
+export function describeProviderOAuth2TokenRequestDefects(oauth2) {
+    const defects = [];
+    for (const [name, value] of Object.entries(oauth2.codeExchangeParameters ?? {})) {
+        if (!PROVIDER_OAUTH2_EXTRA_PARAMETER_NAME.test(name))
+            defects.push(`declares the code-exchange parameter ${JSON.stringify(name)}, which is not a plain parameter name`);
+        else if (PROVIDER_OAUTH2_ENGINE_WRITTEN_TOKEN_PARAMETERS.has(name))
+            defects.push(`declares the code-exchange parameter '${name}', which the engine writes itself`);
+        if (typeof value !== 'string' || value.length === 0)
+            defects.push(`declares the code-exchange parameter ${JSON.stringify(name)} with no value`);
+    }
+    for (const refusal of oauth2.refreshRefusals ?? []) {
+        if (typeof refusal.error !== 'string' || !PROVIDER_OAUTH2_ERROR_CODE_SHAPE.test(refusal.error)) {
+            defects.push(`declares the refresh refusal ${JSON.stringify(refusal.error)}, which is not an OAuth2 error code and would never match`);
+        }
+        else if (refusal.error === 'invalid_grant') {
+            defects.push('declares the refresh refusal \'invalid_grant\', which already retires a connection');
+        }
+        else if (refusal.error === 'invalid_client') {
+            defects.push('declares the refresh refusal \'invalid_client\', which names the application\'s registration, not a person\'s grant');
+        }
+        if (refusal.errorDescription !== undefined && refusal.errorDescription.trim().length === 0) {
+            defects.push(`declares the refresh refusal '${refusal.error}' with an empty errorDescription`);
+        }
+    }
+    return defects;
+}
+/**
+ * Whether a refresh's refusal is one the provider declares as a dead refresh token ({@link ProviderRestOAuth2.refreshRefusals}).
+ * The one reading, shared by the refresh and its tests.
+ */
+export function providerOAuth2RefreshRefusalIsDeclared(oauth2, answer) {
+    return (oauth2.refreshRefusals ?? []).some((refusal) => refusal.error === answer.error
+        && (refusal.errorDescription === undefined || refusal.errorDescription === answer.errorDescription));
+}
 /**
  * The granted scopes a token answer's `scope` string names, read with the vendor's declared delimiter: whitespace (RFC
  * 6749 §5.1) when none is declared, a comma for {@link ProviderOAuth2ScopeListDelimiter.COMMA}.
@@ -595,6 +1080,8 @@ export function describeProviderOAuth2AudienceDefects(oauth2) {
             if (!PROVIDER_OAUTH2_DNS_NAME_PATTERN.test(value.toLowerCase()))
                 defects.push(`audience '${id}' declares the host '${value}', which is not a DNS name`);
         }
+        for (const defect of describeProviderHostSuffixMaxLabelsDefects(audience.hosts.hostSuffixMaxLabels, audience.hosts.hostSuffixes))
+            defects.push(`audience '${id}': ${defect}`);
         if (audience.mintScopes.length === 0)
             defects.push(`audience '${id}' declares no mint scope`);
         for (const scope of audience.mintScopes) {
@@ -618,7 +1105,7 @@ export function describeProviderOAuth2AudienceDefects(oauth2) {
             const [rightId, rightAudience] = entries[right];
             const overlap = leftAudience.hosts.values.some((host) => providerOAuth2AudienceAdmitsHost(rightAudience, host))
                 || rightAudience.hosts.values.some((host) => providerOAuth2AudienceAdmitsHost(leftAudience, host))
-                || (leftAudience.hosts.hostSuffixes ?? []).some((suffix) => (rightAudience.hosts.hostSuffixes ?? []).some((other) => suffix.toLowerCase().endsWith(other.toLowerCase()) || other.toLowerCase().endsWith(suffix.toLowerCase())));
+                || (leftAudience.hosts.hostSuffixes ?? []).some((suffix) => (rightAudience.hosts.hostSuffixes ?? []).some((other) => providerHostSuffixesOverlap({ suffix, ...(leftAudience.hosts.hostSuffixMaxLabels === undefined ? {} : { maxLabels: leftAudience.hosts.hostSuffixMaxLabels }) }, { suffix: other, ...(rightAudience.hosts.hostSuffixMaxLabels === undefined ? {} : { maxLabels: rightAudience.hosts.hostSuffixMaxLabels }) })));
             if (overlap)
                 defects.push(`audiences '${leftId}' and '${rightId}' admit a common host; a request host must select one token`);
         }
@@ -639,7 +1126,122 @@ export var ProviderOAuth2ReportedFactSource;
      * spec-cite: OpenID Connect Core 1.0 §3.1.3.7, item 6.
      */
     ProviderOAuth2ReportedFactSource["ID_TOKEN_CLAIMS"] = "id_token_claims";
+    /**
+     * A query parameter of the AUTHORIZATION REDIRECT that brings the person back with the code (#3397): Intuit's
+     * `realmId`, the QuickBooks company the person chose on the consent screen. `responsePath` is the parameter's name,
+     * one segment. Read by the callback leg, kept with the attempt until the completion leg redeems the code, and recorded
+     * only from that exchange: a refresh has no redirect, so it never restates such a fact and the stored value stands.
+     *
+     * The weakest of the three sources, and restricted for it. The redirect reaches this application through the
+     * browser of the person who authorized, so that person could change the value before it arrives, exactly as they
+     * could type an answer. Such a fact is therefore admitted only where a wrong value harms nobody but the person who
+     * forged it: as a PATH value ({@link ProviderOAuth2ReportedAccountFact.pathSegmentPattern}) of a vendor that checks it
+     * against the token on every call (Intuit answers a realm the token was not granted for with an authorization fault).
+     * It may never be an `origin`, fill a base URL host, or route inbound deliveries, since each of those decides where a
+     * credential goes or which organization receives a message; `describeProviderOAuth2ReportedFactUseDefects` refuses it.
+     */
+    ProviderOAuth2ReportedFactSource["AUTHORIZATION_REDIRECT_QUERY"] = "authorization_redirect_query";
+    /**
+     * The JSON answer of the vendor's USERINFO endpoint ({@link ProviderRestOAuth2.userInfoUrl}, #3397), fetched with the
+     * access token the authorization just minted: DocuSign's `accounts[…].account_id` and `base_uri`. As trustworthy as
+     * the token answer (the vendor answers over TLS, to a request the person's own token authorized), so it may be placed
+     * wherever a token fact may. Read at the authorization-code exchange only: a refresh does not call the endpoint, so it
+     * never restates such a fact and the stored value stands until the person connects again.
+     */
+    ProviderOAuth2ReportedFactSource["USERINFO_RESPONSE"] = "userinfo_response";
 })(ProviderOAuth2ReportedFactSource || (ProviderOAuth2ReportedFactSource = {}));
+/** What reading a {@link ProviderOAuth2ReportedAccountFact.responsePath} out of a vendor's answer found (#3397). */
+export var ProviderReportedFactReadOutcome;
+(function (ProviderReportedFactReadOutcome) {
+    /** A non-empty string or a finite number stood at the path; `value` is its text. */
+    ProviderReportedFactReadOutcome["FOUND"] = "FOUND";
+    /** Nothing usable stood at the path: a missing key, a `null`, an object, an empty string. The fact is not reported. */
+    ProviderReportedFactReadOutcome["ABSENT"] = "ABSENT";
+    /**
+     * A selection segment (`accounts[is_default=true]`) met an array in which NOT EXACTLY ONE element matched. The vendor's
+     * answer does not name one element, so no fact is read from it: guessing the first would address a request to an
+     * account nobody chose. `matched` is how many did.
+     */
+    ProviderReportedFactReadOutcome["SELECTION_NOT_SINGLE"] = "SELECTION_NOT_SINGLE";
+})(ProviderReportedFactReadOutcome || (ProviderReportedFactReadOutcome = {}));
+/** `name` or `name[field=value]`; no `.`, `[`, `]` or `=` inside a name, a field or a value. */
+const PROVIDER_REPORTED_FACT_PATH_SEGMENT_PATTERN = /^([^.[\]=]+)(?:\[([^.[\]=]+)=([^.[\]=]*)\])?$/;
+/**
+ * The steps of a reported fact's `responsePath`, or `undefined` when it is not one (#3397). A path is dot-separated;
+ * each step is an own property name, optionally followed by ONE selection `[field=value]` that picks, out of the array
+ * at that property, the single element whose `field` reads as `value`: `accounts[is_default=true].account_id`.
+ *
+ * Names, fields and values may not contain `.`, `[`, `]` or `=`; a value may be empty. Kept this small on purpose: it
+ * addresses one element by one stated condition, which is what a vendor documenting "the default account" means, and
+ * nothing that would need a query language.
+ */
+export function parseProviderReportedFactPath(path) {
+    if (typeof path !== 'string' || path.length === 0)
+        return undefined;
+    const segments = [];
+    for (const text of path.split('.')) {
+        const match = PROVIDER_REPORTED_FACT_PATH_SEGMENT_PATTERN.exec(text);
+        if (match === null)
+            return undefined;
+        segments.push(match[2] === undefined ? { key: match[1] } : { key: match[1], select: { field: match[2], equals: match[3] } });
+    }
+    return segments;
+}
+/** The text a scalar reads as: a non-empty string, a finite number's decimal text, a boolean's `true`/`false`. */
+function providerReportedScalarText(value, admitBoolean) {
+    if (typeof value === 'string')
+        return value.length > 0 ? value : undefined;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return String(value);
+    if (admitBoolean && typeof value === 'boolean')
+        return String(value);
+    return undefined;
+}
+/**
+ * The value at a reported fact's `responsePath` inside a vendor's JSON answer (#3397): a token answer, the claims of
+ * its ID token, or a userinfo answer. Own properties only (the answer is a vendor's JSON, and `constructor` is not a
+ * fact). A FOUND value is a non-empty string or a finite number's decimal text.
+ *
+ * A selection step keeps the ONE array element whose field reads as the stated value (a string as itself, a number as
+ * its decimal text, a boolean as `true` / `false`, so DocuSign's `is_default: true` matches `[is_default=true]` whether
+ * it is sent as a boolean or a string). Zero or several matches is {@link ProviderReportedFactReadOutcome.SELECTION_NOT_SINGLE}:
+ * two facts selected with the same condition (`accounts[is_default=true].account_id` and `….base_uri`) are therefore
+ * read from the same element or not at all. Anything else that does not lead to a scalar (a missing key, a property
+ * that is not an array where a selection is written, an unparsable path) is ABSENT.
+ */
+export function readProviderReportedFactValue(payload, path) {
+    const segments = parseProviderReportedFactPath(path);
+    if (segments === undefined)
+        return { outcome: ProviderReportedFactReadOutcome.ABSENT };
+    let current = payload;
+    for (const segment of segments) {
+        if (current === null || typeof current !== 'object' || Array.isArray(current) || !Object.hasOwn(current, segment.key)) {
+            return { outcome: ProviderReportedFactReadOutcome.ABSENT };
+        }
+        current = current[segment.key];
+        if (segment.select === undefined)
+            continue;
+        if (!Array.isArray(current))
+            return { outcome: ProviderReportedFactReadOutcome.ABSENT };
+        const { field, equals } = segment.select;
+        const matches = current.filter((element) => element !== null && typeof element === 'object' && !Array.isArray(element)
+            && Object.hasOwn(element, field) && providerReportedScalarText(element[field], true) === equals);
+        if (matches.length !== 1) {
+            return { outcome: ProviderReportedFactReadOutcome.SELECTION_NOT_SINGLE, segment: `${segment.key}[${field}=${equals}]`, matched: matches.length };
+        }
+        current = matches[0];
+    }
+    const value = providerReportedScalarText(current, false);
+    return value === undefined ? { outcome: ProviderReportedFactReadOutcome.ABSENT } : { outcome: ProviderReportedFactReadOutcome.FOUND, value };
+}
+/**
+ * The query parameters an authorization redirect carries for the OAuth protocol itself, never as an account fact: a
+ * redirect-sourced fact named like one would read the code, the state or the error as the account.
+ * spec-cite: RFC 6749 §4.1.2 (`code`, `state`) and §4.1.2.1 (`error`, `error_description`, `error_uri`); RFC 9207 §2
+ * (`iss`).
+ * semantic-literal-boundary: the OAuth protocol's own redirect parameter names, compared with a module's declaration.
+ */
+export const PROVIDER_OAUTH2_REDIRECT_PROTOCOL_PARAMETERS = ['code', 'state', 'error', 'error_description', 'error_uri', 'iss'];
 /** What a {@link ProviderOAuth2IdTokenRequirement} asks of the sign-in's ID token claims. */
 export var ProviderOAuth2IdTokenRequirementKind;
 (function (ProviderOAuth2IdTokenRequirementKind) {
@@ -753,6 +1355,118 @@ export function describeProviderOAuth2IdTokenRequirementDefects(oauth2) {
     }
     return defects;
 }
+/**
+ * Whether a vendor-reported value may stand as one path segment under its fact's declared
+ * {@link ProviderOAuth2ReportedAccountFact.pathSegmentPattern} (#3397): the WHOLE value matches the pattern, and it is
+ * not empty, not a dot-segment and holds no `/`, whatever the pattern admits. The one admission, applied where the value
+ * is captured (the authorization) and where it is spent (every call). A pattern that does not compile admits nothing.
+ */
+export function providerReportedPathSegmentAdmits(pattern, value) {
+    if (value.length === 0 || value === '.' || value === '..' || value.includes('/'))
+        return false;
+    let expression;
+    try {
+        expression = new RegExp(`^(?:${pattern})$`, 'u');
+    }
+    catch {
+        return false;
+    }
+    return expression.test(value);
+}
+/**
+ * What makes the declared USES of a connection's vendor-reported facts unsafe or unusable (#3397), checked at boot with
+ * the contract's other declarations:
+ *
+ * - a fact read from the authorization redirect is something the person who authorized could change, so it may not be
+ *   an `origin`, fill a base URL host, or route inbound deliveries, and its name must be one query parameter that is
+ *   not the OAuth protocol's own (`code`, `state`, …);
+ * - a `pathSegmentPattern` must compile, admit no empty value, and not sit beside an `origin`;
+ * - a `fillsBaseUrlHost` fact must name a `{placeholder}` of the base URL that a `DECLARED_VALUES` allowance governs,
+ *   must not also be an `origin` or something the person is asked at connect, and cannot share a contract with
+ *   `baseUrlConnectionFact`, which already decides where calls go;
+ * - every other `responsePath` must parse ({@link parseProviderReportedFactPath});
+ * - a fact read from the userinfo answer needs a `userInfoUrl`, a `userInfoUrl` needs a fact that reads it (a request
+ *   carrying the person's token that nothing uses is not made), and the userinfo endpoint may carry only the
+ *   host-forming placeholders the token endpoint carries, in the same position (it is the same authorization server).
+ */
+export function describeProviderOAuth2ReportedFactUseDefects(contract) {
+    const defects = [];
+    for (const [name, fact] of Object.entries(contract.oauth2?.reportedAccountFacts ?? {})) {
+        const at = `reported fact '${name}'`;
+        if (fact.source === ProviderOAuth2ReportedFactSource.AUTHORIZATION_REDIRECT_QUERY) {
+            if (fact.responsePath.length === 0 || fact.responsePath.includes('.') || PROVIDER_OAUTH2_REDIRECT_PROTOCOL_PARAMETERS.includes(fact.responsePath)) {
+                defects.push(`${at} reads the redirect query parameter '${fact.responsePath}', which is not one parameter name outside the OAuth protocol's own`);
+            }
+            if (fact.origin !== undefined || fact.fillsBaseUrlHost === true || fact.routesInboundDeliveries === true) {
+                defects.push(`${at} comes from the authorization redirect, which the person authorizing could alter, so it may not decide an origin, a host or delivery routing`);
+            }
+            if (fact.responsePath.includes('['))
+                defects.push(`${at} selects inside the redirect query parameter '${fact.responsePath}', which is one string`);
+        }
+        else if (parseProviderReportedFactPath(fact.responsePath) === undefined) {
+            defects.push(`${at} reads the responsePath ${JSON.stringify(fact.responsePath)}, which is not a dot path of names, each optionally selecting one element as name[field=value]`);
+        }
+        if (fact.source === ProviderOAuth2ReportedFactSource.USERINFO_RESPONSE && contract.oauth2?.userInfoUrl === undefined) {
+            defects.push(`${at} reads the userinfo answer, and the OAuth2 contract declares no userInfoUrl`);
+        }
+        if (fact.pathSegmentPattern !== undefined) {
+            let compiles = true;
+            try {
+                new RegExp(`^(?:${fact.pathSegmentPattern})$`, 'u');
+            }
+            catch {
+                compiles = false;
+            }
+            if (!compiles)
+                defects.push(`${at} declares the pathSegmentPattern ${JSON.stringify(fact.pathSegmentPattern)}, which does not compile`);
+            else if (new RegExp(`^(?:${fact.pathSegmentPattern})$`, 'u').test(''))
+                defects.push(`${at} declares a pathSegmentPattern that admits an empty value`);
+            if (fact.origin !== undefined)
+                defects.push(`${at} is both an origin and a path value; a fact addresses the account one way`);
+        }
+        if (fact.fillsBaseUrlHost === true) {
+            if (fact.origin !== undefined)
+                defects.push(`${at} is both an origin and a base URL host; a fact addresses the account one way`);
+            if (contract.baseUrlConnectionFact !== undefined)
+                defects.push(`${at} fills a base URL host beside baseUrlConnectionFact, and only one may decide where a call goes`);
+            if (contract.baseUrl === undefined || !contract.baseUrl.includes(`{${name}}`))
+                defects.push(`${at} fills a base URL host, and the base URL carries no '{${name}}' placeholder`);
+            const allowance = contract.baseUrlHostAllowances !== undefined && Object.hasOwn(contract.baseUrlHostAllowances, name) ? contract.baseUrlHostAllowances[name] : undefined;
+            if (allowance?.kind !== ProviderOAuth2EndpointHostAllowanceKind.DECLARED_VALUES) {
+                defects.push(`${at} fills a base URL host that no DECLARED_VALUES baseUrlHostAllowances entry governs`);
+            }
+            if ((contract.oauth2?.connectionParameters ?? []).includes(name))
+                defects.push(`${at} fills a base URL host the person is also asked for at connect`);
+        }
+    }
+    const userInfoUrl = contract.oauth2?.userInfoUrl;
+    if (userInfoUrl !== undefined) {
+        const facts = Object.values(contract.oauth2?.reportedAccountFacts ?? {});
+        if (!facts.some((fact) => fact.source === ProviderOAuth2ReportedFactSource.USERINFO_RESPONSE)) {
+            defects.push('declares a userInfoUrl that no reported fact reads, so the person\'s token would be sent there for nothing');
+        }
+        const templateDefects = findProviderOAuth2EndpointTemplateDefects(userInfoUrl);
+        if (templateDefects.length > 0 || !userInfoUrl.toLowerCase().startsWith('https://')) {
+            defects.push(`declares the userInfoUrl '${userInfoUrl}', which is not an https endpoint template (${templateDefects.join(', ') || 'not https'})`);
+        }
+        else {
+            const tokenPositions = new Map();
+            if (contract.oauth2?.tokenUrl !== undefined && findProviderOAuth2EndpointTemplateDefects(contract.oauth2.tokenUrl).length === 0) {
+                for (const occurrence of classifyProviderOAuth2EndpointPlaceholders(contract.oauth2.tokenUrl))
+                    tokenPositions.set(occurrence.name, occurrence.position);
+            }
+            for (const occurrence of classifyProviderOAuth2EndpointPlaceholders(userInfoUrl)) {
+                if (occurrence.position === ProviderOAuth2EndpointPlaceholderPosition.PATH_OR_QUERY) {
+                    defects.push(`the userInfoUrl carries the path placeholder '{${occurrence.name}}'; it is one fixed endpoint of the authorization server`);
+                }
+                else if (tokenPositions.get(occurrence.name) !== occurrence.position) {
+                    defects.push(`the userInfoUrl's host placeholder '{${occurrence.name}}' is not the token endpoint's own, in the same position; both belong to one authorization server`);
+                }
+            }
+        }
+    }
+    return defects;
+}
 /** How a placeholder's value is compared with a declared one. */
 export var ProviderOAuth2ValueComparison;
 (function (ProviderOAuth2ValueComparison) {
@@ -993,6 +1707,91 @@ export var ProviderOAuth2EndpointTemplateDefect;
  * hyphen; 63 octets per label).
  */
 export const PROVIDER_OAUTH2_DNS_NAME_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$/;
+/**
+ * Whether `host` is `<labels><suffix>`: it ends with the dotted `suffix`, what precedes the suffix is a DNS name (never
+ * empty, so the bare suffix is not admitted), and that DNS name carries at most `maxLabels` labels (#3640).
+ *
+ * THE one suffix test. Every place a declared host suffix admits a host — an answer filled into an endpoint or a base URL,
+ * an audience selecting a request host, the token-endpoint host description, a declined value a suffix would still admit —
+ * asks this function, so a label bound declared once holds at all of them. `maxLabels` absent means unbounded, which is
+ * what every suffix meant before the bound existed. A bound that is not a positive integer admits nothing (fail closed):
+ * the declaration checks refuse it where a person is reading a diff, and this keeps the runtime closed regardless.
+ *
+ * Case-insensitive; the caller need not lower-case.
+ */
+export function providerHostIsUnderSuffix(host, suffix, maxLabels) {
+    const candidate = host.toLowerCase();
+    const lowered = suffix.toLowerCase();
+    if (!lowered.startsWith('.') || !candidate.endsWith(lowered) || candidate.length === lowered.length)
+        return false;
+    const labels = candidate.slice(0, candidate.length - lowered.length);
+    if (!PROVIDER_OAUTH2_DNS_NAME_PATTERN.test(labels))
+        return false;
+    return maxLabels === undefined || labels.split('.').length <= maxLabels;
+}
+/**
+ * Whether some host is admitted under BOTH suffixes (#3640). Two suffixes can only share a host when one ends with the
+ * other (`.a.b` and `.b`): a host under the longer one carries the extra labels (`.a`) before the shorter one, so the
+ * shorter one's bound must leave room for one label of its own plus those. Equal suffixes always share a host.
+ */
+export function providerHostSuffixesOverlap(left, right) {
+    const leftSuffix = left.suffix.toLowerCase();
+    const rightSuffix = right.suffix.toLowerCase();
+    const [longer, shorter] = leftSuffix.length >= rightSuffix.length ? [left, right] : [right, left];
+    const longerSuffix = longer.suffix.toLowerCase();
+    const shorterSuffix = shorter.suffix.toLowerCase();
+    if (!longerSuffix.endsWith(shorterSuffix))
+        return false;
+    // The probe host: one label under the longer suffix, which is the fewest labels any host under it carries.
+    return providerHostIsUnderSuffix(`a${longerSuffix}`, longerSuffix, longer.maxLabels) && providerHostIsUnderSuffix(`a${longerSuffix}`, shorterSuffix, shorter.maxLabels);
+}
+/**
+ * The bare answer for a placeholder that OPENS a host, when the person typed the whole host (#3640).
+ *
+ * `https://{shop}.myshopify.com` asks for the store's handle, and the person connecting sees `acme.myshopify.com` in the
+ * vendor's own screens. Filled verbatim, that answer dials `acme.myshopify.com.myshopify.com`: a host the suffix admits
+ * (it ends in `.myshopify.com`) that does not exist, so every request fails on DNS naming a host rather than the answer.
+ * The literal text the template writes after the placeholder (`literalHostSuffix`) is therefore stripped ONCE from an
+ * answer that ends with it: `acme.myshopify.com` → `acme`. Nothing else is rewritten; the result is then admitted like
+ * any other answer, so an answer with too many labels left (`acme.evil.myshopify.com` → `acme.evil` under a one-label
+ * bound) is still refused.
+ *
+ * Generic rather than per vendor, because it is a property of the TEMPLATE: every provider whose host opens with a
+ * placeholder (Shopify, Zendesk) asks for the part before a literal the vendor shows people with it attached. Done where
+ * the template is filled, not in a connect prompt, so the OAuth start, the stored-answer re-admission and every
+ * operation's base URL read the same answer the same way, whichever screen or flag supplied it. A host that literally
+ * repeated its suffix is never a real vendor host, so nothing a person could mean is lost.
+ */
+export function stripProviderHostAnswerTemplateSuffix(value, literalHostSuffix) {
+    if (literalHostSuffix === undefined || literalHostSuffix === '')
+        return value;
+    return value.length > literalHostSuffix.length && value.toLowerCase().endsWith(literalHostSuffix.toLowerCase())
+        ? value.slice(0, value.length - literalHostSuffix.length)
+        : value;
+}
+/**
+ * The words a refusal uses for the answer a bounded suffix expects (#3640): `a single DNS label before .myshopify.com
+ * (the 'acme' of acme.myshopify.com)`. Shared so every refusal names the same form.
+ */
+export function describeProviderHostSuffixExpectedForm(suffix, maxLabels, answerExcludesSuffix) {
+    const count = maxLabels === undefined ? 'DNS labels' : maxLabels === 1 ? 'a single DNS label' : `at most ${maxLabels} DNS labels`;
+    const example = answerExcludesSuffix ? `the 'acme' of acme${suffix}` : `acme${suffix}`;
+    return `${count} before ${suffix} (${example})`;
+}
+/**
+ * Why a declared label bound on host suffixes cannot be honoured (#3640): it is not a positive integer, or there is no
+ * suffix for it to bound. Shared by the endpoint allowances and the audiences, so both refuse the same shapes.
+ */
+export function describeProviderHostSuffixMaxLabelsDefects(maxLabels, hostSuffixes) {
+    if (maxLabels === undefined)
+        return [];
+    const defects = [];
+    if (!Number.isInteger(maxLabels) || maxLabels < 1)
+        defects.push(`hostSuffixMaxLabels ${String(maxLabels)} is not a positive integer, which admits no host`);
+    if ((hostSuffixes ?? []).length === 0)
+        defects.push('hostSuffixMaxLabels is declared with no hostSuffixes to bound');
+    return defects;
+}
 /**
  * Why a DECLARED host allowance cannot be applied where its placeholder sits — the position rules the
  * transposer enforces at GENERATION time, so a broken declaration refuses the batch instead of being
@@ -1076,10 +1875,13 @@ export function describeProviderOAuth2EndpointHostAllowanceDefects(placeholder,
             defects.push(`host suffix '${suffix}' must begin with '.' and name at least two DNS labels (a bare '.com' admits every host under a TLD)`);
         }
     }
+    defects.push(...describeProviderHostSuffixMaxLabelsDefects(allowance.hostSuffixMaxLabels, allowance.hostSuffixes));
     defects.push(...describeProviderOAuth2UnsupportedValueDefects(allowance.unsupportedValues, allowance.values, ProviderOAuth2ValueComparison.CASE_INSENSITIVE));
     for (const declined of Object.keys(allowance.unsupportedValues ?? {})) {
         // A declined value a declared SUFFIX would still admit is admitted, whatever the reason says.
-        const coveringSuffix = (allowance.hostSuffixes ?? []).find((suffix) => declined.toLowerCase().endsWith(suffix.toLowerCase()));
+        // ORIGIN values carry the scheme; the suffix is matched against the host they name.
+        const declinedHost = declined.toLowerCase().replace(/^https:\/\//, '');
+        const coveringSuffix = (allowance.hostSuffixes ?? []).find((suffix) => providerHostIsUnderSuffix(declinedHost, suffix, allowance.hostSuffixMaxLabels));
         if (coveringSuffix !== undefined)
             defects.push(`'${declined}' is declared unsupported but the host suffix '${coveringSuffix}' admits it`);
     }