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

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

@@ -46,7 +46,8 @@
 import { z } from 'zod';
 import { API_HttpMethod } from '../core/commons.external-connectors-models.schemas';
 import { ExternalOperation_Classification } from '../core/operation-classification.external-connectors-models.schemas';
-import type { ExternalProvider_ConnectionTarget } from '../core/security.external-connectors-models.schemas';
+import { ExternalProvider_Connection_OwnerScope, type ExternalProvider_ConnectionTarget } from '../core/security.external-connectors-models.schemas';
+import type { ProviderRestOperationGraphql } from './graphql-operations.external-connectors-models.schemas';
 /** @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 declare enum ProviderRestParameterLocation {
@@ -140,6 +141,19 @@ export interface ProviderRestOperationParameter {
      * above it; the origin itself cannot move, as for every path value.
      */
     readonly multiSegment?: true;
+    /**
+     * PATH only (#3397): the value is the CONNECTION's vendor-reported fact of this name, never the caller's input. Every
+     * QuickBooks path is `/v3/company/{realmId}/…`, and the company is the one the person connected, so asking each caller
+     * for it would let a call name a company its connection was not made for and leave every application re-typing it.
+     *
+     * The fact must be declared on the connection's OAuth2 contract with a
+     * {@link ProviderOAuth2ReportedAccountFact.pathSegmentPattern}; the access resolver re-admits the stored value on every
+     * call and hands it to the request compiler, which fills nothing else from it. A caller value under the same input
+     * name is refused rather than ignored, and the operation's `inputSchema` must not declare one
+     * ({@link describeProviderRestOperationConnectionFactDefects}). Exclusive with `from`, `constantValue` and
+     * `multiSegment`.
+     */
+    readonly connectionFact?: string;
     readonly description?: string;
 }
 /** How the request body is built from the operation's input. */
@@ -208,12 +222,50 @@ export interface ProviderRestOperationInputOptions {
     /** Dot-path, inside each listed item, to the text a person reads (`name`). Vendor content, never derived from the value. */
     readonly labelPath: string;
     /**
-     * Inputs the options depend on: `{ <options-operation input field>: <this operation's input field> }`.
+     * Inputs the options depend on: `{ <options-operation input field>: <this operation's input field PATH> }`.
+     * The value side is a dot path into this operation's input, like the `inputOptions` key (#3399): Jira's issue
+     * types depend on `project.key`. The key side is a top-level field of the options operation's own input.
      * A choice that is not yet made is REFUSED by name rather than listed as empty — "no projects" and
      * "choose a workspace first" are different answers, and only one of them is true.
      */
     readonly dependsOn?: Readonly<Record<string, string>>;
+    /**
+     * Fixed values the options operation is called with, beside what `dependsOn` forwards (#3399): Jira lists only the
+     * projects a person may create in (`action: 'create'`), Box lists the root folder (`folder_id: '0'`). A field may
+     * not be both fixed and forwarded.
+     */
+    readonly input?: Readonly<Record<string, string | number | boolean>>;
+    /**
+     * Dot path, inside the options operation's output, to the listed items, when that output is an object rather than the
+     * list itself (#3399): QuickBooks answers a query as `{ Customer: [...] }`, Box a folder as `{ entries: [...] }`. An
+     * object without that path lists nothing, which is how QuickBooks answers a query with no rows; anything else at the
+     * path that is not a list is an unreadable answer. Absent, the output itself must be the list.
+     */
+    readonly itemsPath?: string;
+    /**
+     * Keeps only the listed items whose value at each dot path equals the given text (#3399): a folder's items are files,
+     * folders and web links, and only a folder can be a parent (`{ type: 'folder' }`). Absent, every item is a choice.
+     */
+    readonly itemWhere?: Readonly<Record<string, string>>;
 }
+/**
+ * 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 declare function describeProviderRestOperationInputOptionsDefects(operation: Pick<ProviderRestOperation, 'operationId' | 'inputSchema' | 'inputOptions'>): string[];
+/**
+ * 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 declare function describeProviderRestOperationConnectionFactDefects(operation: Pick<ProviderRestOperation, 'operationId' | 'pathTemplate' | 'parameters' | 'inputSchema'>, reportedAccountFacts?: Readonly<Record<string, ProviderOAuth2ReportedAccountFact>>): string[];
 /**
  * A provider operation, hand-authored. The unit an application addresses:
  * `executeProviderOperation({ providerRef: 'slack', operationId: 'conversations.list', input })`.
@@ -315,10 +367,19 @@ export interface ProviderRestOperation {
     /** Narrows the provider's semantics for this one operation (a slow export, a tight endpoint). */
     readonly remoteCallSemantics?: Partial<ProviderRestCallSemantics>;
     /**
-     * Where each input's choices come from, keyed by INPUT field name. Absent for an input a caller types.
-     * See {@link ProviderRestOperationInputOptions}.
+     * Where each input's choices come from, keyed by a dot PATH into the input (#3399): `workspace` for a top-level
+     * field, `project.key` or `CustomerRef.value` for the value a vendor nests inside a reference object. Absent for an
+     * input a caller types. Every path must name a field of `inputSchema`
+     * ({@link describeProviderRestOperationInputOptionsDefects}). See {@link ProviderRestOperationInputOptions}.
      */
     readonly inputOptions?: Readonly<Record<string, ProviderRestOperationInputOptions>>;
+    /**
+     * Present for a GraphQL operation (#3392): the provider-owned document the call sends to `pathTemplate` (the vendor's
+     * GraphQL endpoint), with the operation's input as its variables. A 2xx answer carrying `errors` fails the call; the
+     * output is read from the answer's `data`. See {@link ProviderRestOperationGraphql} for what such an operation may and
+     * may not declare beside it.
+     */
+    readonly graphql?: ProviderRestOperationGraphql;
     /** Set when the vendor has deprecated it; the executor logs once per operation, never refuses. */
     readonly deprecated?: {
         readonly reason: string;
@@ -420,6 +481,22 @@ export declare function describeProviderRestApplicationOutcomeDefects(outcome: P
 export declare 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 declare const PROVIDER_CLIENT_CREDENTIALS_TENANT_SHAPE: RegExp;
+/**
+ * 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 declare const PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER = "{deploymentOrigin}";
 /** What a {@link ProviderClientCredentialsVerifiedFact} records: a value the person typed and the vendor accepted. */
 export declare enum ProviderClientCredentialsFactSource {
     /** The client id the token endpoint issued a token for: Microsoft's bot App ID. */
@@ -451,9 +528,14 @@ export interface ProviderClientCredentialsVerifiedFact {
  * secret the connection holds (#2663). The Bot Framework is the first: a Teams bot's App ID and secret, and for a
  * single-tenant bot the tenant it is registered in, mint a token for `https://api.botframework.com/.default`.
  *
+ * Declared beside `oauth2` (#3398), it is the APPLICATION's own connection: Box's client-credentials grant and Zoom's
+ * server-to-server OAuth renew the application's token while people and organizations connect through the exchange.
+ * {@link providerClientCredentialsServesOwnerScope} says which door a connection takes.
+ *
  * The token is minted per call when no unexpired one is cached, never stored, and attached where
- * {@link ProviderProtocolRuntimeContract}'s `apiKey` says, so `apiKey.secretRef` names the client SECRET (the slot
- * whose absence means "not configured"). The client id, secret and tenant are read from the connection: the
+ * {@link ProviderProtocolRuntimeContract}'s `apiKey` says, so (with no `oauth2` beside it) `apiKey.secretRef` names the
+ * client's credential, its SECRET or its private key (#3402), the slot whose absence means "not configured". The
+ * client id, credential and tenant are read from the connection: the
  * application's own environment for an APPLICATION connection, the organization's typed credential for an
  * ORGANIZATION one.
  *
@@ -468,16 +550,62 @@ export interface ProviderClientCredentialsVerifiedFact {
  * `https://api.botframework.com/.default`, fetched 2026-10-06.
  */
 export interface ProviderRestClientCredentials {
-    /** The https token endpoint. May carry {@link PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER}. */
+    /**
+     * The https token endpoint. May carry {@link PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER}, or BEGIN with
+     * {@link PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER} when the token endpoint is on the deployment's own
+     * vendor instance (Okta's org, #3402).
+     */
     readonly tokenUrl: string;
-    /** The hosts the token endpoint may be on once filled. The client secret is sent nowhere else. */
+    /**
+     * The hosts the token endpoint may be on once filled. The client secret is sent nowhere else. EMPTY exactly when the
+     * token URL begins with {@link PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER}: its host is the one the
+     * operator named for the operations, and no fixed list can name it.
+     */
     readonly tokenHosts: readonly string[];
-    /** The `scope` parameter, sent as written. */
-    readonly scope: string;
+    /**
+     * The `scope` parameter, sent as written. Omitted, no `scope` is sent: RFC 6749 makes it optional, and Box, Zoom and
+     * Salesforce grant the scopes configured on the app instead (#3398).
+     * spec-cite: RFC 6749 §4.4.2 — `scope`: "OPTIONAL. The scope of the access request as described by Section 3.3."
+     * Fetched 2026-10-06.
+     */
+    readonly scope?: string;
+    /**
+     * The `grant_type` sent. Omitted, `client_credentials` (RFC 6749 §4.4). See {@link ProviderClientCredentialsGrantType}.
+     */
+    readonly grantType?: ProviderClientCredentialsGrantType;
+    /**
+     * Further parameters of the token request a vendor requires, by name: a fixed value, or one read from a slot of the
+     * connection (#3398). Box's client-credentials grant names the subject it authenticates as (`box_subject_type`,
+     * `box_subject_id`); Zoom's server-to-server grant names the account (`account_id`). A parameter the grant itself
+     * defines (`grant_type`, `client_id`, `client_secret`, `scope`, the client assertion) is refused here: each has its own
+     * field. See {@link ProviderClientCredentialsTokenRequestParameter}.
+     */
+    readonly tokenRequestParameters?: Readonly<Record<string, ProviderClientCredentialsTokenRequestParameter>>;
+    /**
+     * How the client authenticates to the token endpoint. Omitted,
+     * {@link ProviderOAuth2ClientAuthenticationMethod.CLIENT_SECRET_POST} with a client secret: the id and secret in the
+     * body, as Microsoft's identity platform documents. {@link ProviderOAuth2ClientAuthenticationMethod.CLIENT_SECRET_BASIC}
+     * sends them in the Basic header only (Zoom's server-to-server OAuth documents nothing else). With
+     * {@link privateKeyJwt} the method is {@link ProviderOAuth2ClientAuthenticationMethod.PRIVATE_KEY_JWT}, implied when
+     * omitted (#3402).
+     */
+    readonly tokenEndpointAuthMethod?: ProviderOAuth2ClientAuthenticationMethod;
     /** The slot holding the client id. */
     readonly clientIdSecretRef: string;
-    /** The slot holding the client secret. Equal to the contract's `apiKey.secretRef`. */
-    readonly clientSecretSecretRef: string;
+    /**
+     * The slot holding the client secret. Exactly one of this and {@link privateKeyJwt} (#3402): a client authenticates
+     * with a shared secret or with a key it alone holds, never both. The client's CREDENTIAL slot (this one, or the
+     * private key's) equals the contract's `apiKey.secretRef` when the contract declares no `oauth2` (the slot whose
+     * absence means "not configured"); beside `oauth2`, `apiKey.secretRef` is the slot of the people's and organizations'
+     * minted tokens and this one serves the application alone.
+     */
+    readonly clientSecretSecretRef?: string;
+    /**
+     * The client authenticates with a JWT it signs with its own private key (`private_key_jwt`, #3402) instead of a
+     * secret: Okta's OAuth service apps accept nothing else for the Management API. See
+     * {@link ProviderClientCredentialsPrivateKeyJwt}.
+     */
+    readonly privateKeyJwt?: ProviderClientCredentialsPrivateKeyJwt;
     /** The slot filling {@link PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER}. Required exactly when the token URL carries it. */
     readonly tenantSecretRef?: string;
     /** Facts an ORGANIZATION connection records once the vendor accepted its credential, keyed by fact name. */
@@ -485,12 +613,171 @@ export interface ProviderRestClientCredentials {
     /** Seconds a token is kept when the answer states no `expires_in`. Omitted, it is not cached. */
     readonly tokenLifetimeFallbackSeconds?: number;
 }
+/**
+ * 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 declare enum 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.
+     */
+    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.
+     */
+    ACCOUNT_CREDENTIALS = "account_credentials"
+}
+/**
+ * One further parameter of a client-credentials token request ({@link ProviderRestClientCredentials.tokenRequestParameters}):
+ * a fixed `value` the module states (`box_subject_type: enterprise`), or a `secretRef` naming the connection slot that
+ * holds it (Box's enterprise id, Zoom's account id), read like the client id: from the application's environment for
+ * the application's connection, from the organization's credential for an organization's.
+ */
+export type ProviderClientCredentialsTokenRequestParameter = {
+    readonly value: string;
+    readonly secretRef?: never;
+} | {
+    readonly secretRef: string;
+    readonly value?: never;
+};
+/**
+ * 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 declare enum ProviderClientAssertionSigningAlgorithm {
+    /** ECDSA on P-256 with SHA-256: a short key and signature, and the default to choose for a new key. */
+    ES256 = "ES256",
+    /** RSASSA-PKCS1-v1_5 with SHA-256, for a vendor or key store that issues RSA keys. */
+    RS256 = "RS256"
+}
+/** The longest a client assertion may live: Okta refuses one whose `exp` is more than an hour away. */
+export declare 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 declare const PROVIDER_CLIENT_ASSERTION_DEFAULT_LIFETIME_SECONDS = 300;
+/**
+ * `private_key_jwt` client authentication for a client-credentials token request (#3402). The client signs, per token
+ * request, a JWT whose `iss` and `sub` are its client id, whose `aud` is the token endpoint it is sent to, with a short
+ * `exp` and a fresh `jti`, and sends it as `client_assertion`.
+ *
+ * The private key is read from a slot of the connection, as an unencrypted PEM (PKCS#8, or an RSA PKCS#1 / EC key the
+ * signer re-wraps), like a secret: the application's configured provider secrets for its own connection, an organization's sealed
+ * credential row for an organization's.
+ *
+ * ## Why the platform keyring does not hold this key (decided 2026-11-10, #3402)
+ *
+ * The key layer (#2916) holds keys by PURPOSE, each signing the platform's own claims under its own `typ` and verified
+ * from public halves the platform publishes. A client key is the opposite: its public half is REGISTERED BY THE OPERATOR
+ * at the vendor (Okta's app, a Google service account), the vendor is its only verifier, and the vendor fixes the
+ * algorithm (Okta's console and Google's uploaded keys are RSA, while the keyring signs ES256 only). A keyring rotation
+ * would also silently break every connection whose vendor still holds the old public half. So custody signing for vendor
+ * clients is a key purpose of its own (RS256 across the keyring providers, a public half handed to the operator, rotation
+ * coordinated with the vendor registration), recorded on #2916, and not a missing step of this declaration.
+ *
+ * spec-cite: RFC 7523 §2.2 — "The value of the "client_assertion_type" is
+ * "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"."; §3 — the JWT "MUST contain an "iss" (issuer) claim", for
+ * client authentication "the subject MUST be the "client_id" of the OAuth client", an "aud" (audience) claim "containing
+ * a value that identifies the authorization server", and an "exp" (expiration time) claim; OpenID Connect Core 1.0 §9,
+ * `private_key_jwt` — `iss` and `sub` "MUST contain the client_id of the OAuth Client", "The Audience SHOULD be the URL
+ * of the Authorization Server's Token Endpoint", `jti` REQUIRED: "These tokens MUST only be used once". Fetched
+ * 2026-11-09 from https://www.rfc-editor.org/rfc/rfc7523 and https://openid.net/specs/openid-connect-core-1_0.html.
+ */
+export interface ProviderClientCredentialsPrivateKeyJwt {
+    /** The slot holding the client's private key: an unencrypted PEM, PKCS#8 (`-----BEGIN PRIVATE KEY-----`) or PKCS#1 / EC. */
+    readonly privateKeySecretRef: string;
+    /** The JWS algorithm the key signs with. Must match the key: an EC P-256 key for ES256, an RSA key for RS256. */
+    readonly algorithm: ProviderClientAssertionSigningAlgorithm;
+    /**
+     * The slot holding the key id sent as the assertion's `kid` header, when the vendor locates the key by it (Okta
+     * requires a `kid` on every key registered with the app). Omitted, no `kid` is sent.
+     */
+    readonly keyIdSecretRef?: string;
+    /** Seconds until the assertion's `exp`. Omitted, {@link PROVIDER_CLIENT_ASSERTION_DEFAULT_LIFETIME_SECONDS}. */
+    readonly assertionLifetimeSeconds?: number;
+}
+/**
+ * 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 declare function providerClientCredentialsCredentialSlot(credentials: ProviderRestClientCredentials): string | undefined;
+/**
+ * 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 declare const PROVIDER_CLIENT_CREDENTIALS_RESERVED_PARAMETER_NAMES: readonly string[];
+/**
+ * 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 declare function providerClientCredentialsServesOwnerScope(contract: {
+    readonly clientCredentials?: ProviderRestClientCredentials;
+    readonly oauth2?: unknown;
+}, ownerScope: ExternalProvider_Connection_OwnerScope): boolean;
+/**
+ * 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 declare function providerRestConnectionCredentialSlot(contract: {
+    readonly clientCredentials?: ProviderRestClientCredentials;
+    readonly oauth2?: unknown;
+    readonly apiKey?: {
+        readonly secretRef?: string;
+    };
+}, ownerScope: ExternalProvider_Connection_OwnerScope): string | undefined;
 /**
  * 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
  * with no tenant slot (or the reverse), or any other placeholder in the URL.
  */
 export declare function describeProviderRestClientCredentialsDefects(credentials: ProviderRestClientCredentials): string[];
+/**
+ * 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 declare function describeProviderRestClientCredentialsPlacementDefects(contract: {
+    readonly clientCredentials?: ProviderRestClientCredentials;
+    readonly oauth2?: unknown;
+    readonly requestSigning?: unknown;
+    readonly apiKey: {
+        readonly secretRef: string;
+    };
+    readonly baseUrlHostEnvVarName?: string;
+    readonly baseUrlEnvVarName?: string;
+}, admitsApplicationConnection: boolean, 
+/** Whether the module admits an ORGANIZATION or USER connection. Omitted, `false`. */
+admitsNonApplicationConnection?: boolean): string[];
 /**
  * The vendor's error code at `errorCodePath` in a parsed answer, when it is code-shaped. Used for a refused 2xx and for
  * a non-2xx answer alike: a vendor that states its code in the body states it in the same place whatever the status.
@@ -702,8 +989,108 @@ export interface ProviderRestOAuth2 {
      *
      * Absent — not empty — when no revocation is declared, so "this vendor cannot be told" stays
      * distinguishable from "nobody has looked".
+     *
+     * The client authenticates here exactly as it does at the token endpoint ({@link tokenEndpointAuthMethod}), and the
+     * body is form-encoded unless {@link revocationRequestBodyEncoding} says otherwise: a vendor that takes RFC 7009's
+     * `token` parameter and answers its 200, but wants Basic or a JSON body, is still declared here.
      */
     readonly rfc7009RevocationUrl?: string;
+    /**
+     * The vendor's USERINFO endpoint (#3397): a GET carrying the access token the authorization just minted as a Bearer
+     * credential, whose JSON answer is read by every fact declared with
+     * {@link ProviderOAuth2ReportedFactSource.USERINFO_RESPONSE}. DocuSign names the connected account and its API host
+     * nowhere else: `GET https://account(-d).docusign.com/oauth/userinfo` lists the person's `accounts`, each with its
+     * `account_id` and `base_uri`.
+     *
+     * Called ONCE, at the authorization-code exchange that makes (or remakes) the connection, and only when some fact
+     * reads it; never at a refresh. The vendor's own guidance is to call it at setup and store the answer, and DocuSign
+     * enforces an hourly limit on these requests per user and per integration key, so a call per refresh would spend that
+     * limit to restate facts that change "very infrequently".
+     * spec-cite: DocuSign, "UserInfo" (https://developers.docusign.com/platform/auth/reference/user-info/, fetched
+     * 2026-11-09) — "Your integration should call this method to get the information needed to begin making API calls
+     * during setup, then store it for use in future calls" and "Docusign enforces hourly limits on the number of
+     * `/oauth/userinfo` requests per user ID and per integration key".
+     *
+     * Resolved like {@link tokenUrl}, through the same {@link endpointHostAllowances} and deployment values, because it
+     * receives a credential too (the person's access token). It belongs to the same authorization server, so it may carry
+     * only the host-forming placeholders the token endpoint carries, each in the same position
+     * ({@link describeProviderOAuth2ReportedFactUseDefects}); every reader of "which placeholders does this client have"
+     * therefore stays complete reading the authorize and token endpoints alone. A redirect is refused, never followed.
+     */
+    readonly userInfoUrl?: string;
+    /**
+     * How the client authenticates to the vendor's token endpoint: at the code exchange, at every refresh (and every
+     * per-audience mint, which is a refresh), and at the revocation endpoint. Named after the client metadata field
+     * `token_endpoint_auth_method`, whose values it uses. See {@link ProviderOAuth2ClientAuthenticationMethod}.
+     *
+     * Absent means {@link ProviderOAuth2ClientAuthenticationMethod.CLIENT_SECRET_POST}: `client_id` and `client_secret` in
+     * the body, the engine's behaviour before this field existed, so no existing provider sends a different byte. Declare
+     * {@link ProviderOAuth2ClientAuthenticationMethod.CLIENT_SECRET_BASIC} for a vendor that documents the Basic header
+     * (Zoom, Notion, Intuit). With Basic the body carries neither `client_id` nor `client_secret`: the header identifies
+     * the client, and a credential is sent on one channel only.
+     * spec-cite: RFC 6749 §4.1.3 — `client_id` is "REQUIRED, if the client is not authenticating with the authorization
+     * server" as Section 3.2.1 describes. Fetched 2026-11-06.
+     *
+     * ## Why the revocation endpoint does not get a method of its own
+     *
+     * RFC 7009 sends the client's credentials at the revocation endpoint "as described in Section 2.3. of [RFC6749]", the
+     * same section as the token endpoint, and every vendor measured on 2026-11-06 (Zoom, Notion, Intuit) authenticates
+     * both endpoints the same way. A separate member would be a choice no vendor has needed; it is added when one does.
+     * spec-cite: RFC 7009 §2.1 — "The client also includes its authentication credentials as described in Section 2.3.
+     * of [RFC6749]." Fetched 2026-11-06.
+     */
+    readonly tokenEndpointAuthMethod?: ProviderOAuth2ClientAuthenticationMethod;
+    /**
+     * How the token request's parameters are written (exchange, refresh, per-audience mint). Absent means
+     * {@link ProviderOAuth2RequestBodyEncoding.FORM}, as RFC 6749 specifies. Notion's token endpoint takes JSON only.
+     */
+    readonly tokenRequestBodyEncoding?: ProviderOAuth2RequestBodyEncoding;
+    /**
+     * Extra parameters the AUTHORIZATION-CODE exchange carries beside the specification's own (follow-up to #3392), each a
+     * fixed value the provider module owns: a vendor that issues a different kind of token when asked in the exchange.
+     * Shopify issues an expiring offline token (an hour, with a refresh token) only when the exchange carries `expiring=1`,
+     * and a non-expiring one otherwise; a public app on non-expiring tokens is refused from April 2027.
+     * spec-cite: https://shopify.dev/docs/apps/build/authentication-authorization/access-tokens — the `expiring` row: "Set
+     * to `1` for an expiring offline token, or `0` (default) for a non-expiring one.", fetched 2026-11-10.
+     *
+     * Sent at the code exchange only: a refresh renews the grant the exchange made and Shopify's refresh request carries no
+     * such parameter. A name the engine writes itself (`grant_type`, `code`, `redirect_uri`, `code_verifier`, the client's
+     * credentials, `refresh_token`, `scope`) is refused, so a declaration cannot change what the exchange is
+     * ({@link describeProviderOAuth2TokenRequestDefects}).
+     *
+     * @example
+     * codeExchangeParameters: { expiring: '1' }
+     */
+    readonly codeExchangeParameters?: Readonly<Record<string, string>>;
+    /**
+     * The refusals of a REFRESH that the vendor documents as a dead refresh token, beside the specification's
+     * `invalid_grant` (follow-up to #3392). A refresh refused with one of them retires the stored connection the way
+     * `invalid_grant` does, rather than being retried at every call. Shopify answers a refresh token that can no longer be
+     * used with `invalid_request` and a fixed description, and says to treat it as final.
+     * spec-cite: https://shopify.dev/docs/api/usage/response-codes — "A refresh token that can no longer be used returns this
+     * status with the error code `invalid_request` and the description `This request requires an active refresh_token`.
+     * Treat it as final rather than retrying.", fetched 2026-11-10.
+     *
+     * `error` is the OAuth2 `error` code. `errorDescription`, when given, must equal the answer's `error_description`
+     * exactly: `invalid_request` alone also names a malformed request, which says nothing about the person's grant, so a
+     * vendor that reuses a generic code is matched on its description too. Read at a refresh only, never at the exchange.
+     * `invalid_client` is refused: it names the APPLICATION's registration, and retiring every connection over it would
+     * blame the people who connected (see `providerOAuth2GrantWasPermanentlyRejected`).
+     *
+     * @example
+     * refreshRefusals: [{ error: 'invalid_request', errorDescription: 'This request requires an active refresh_token' }]
+     */
+    readonly refreshRefusals?: readonly ProviderOAuth2RefreshRefusal[];
+    /**
+     * How the revocation request's parameters are written. Absent means {@link ProviderOAuth2RequestBodyEncoding.FORM}, as
+     * RFC 7009 specifies, whatever {@link tokenRequestBodyEncoding} says: the two encodings are declared separately because
+     * a vendor can differ between its two endpoints. Intuit's own client library form-encodes the token request and sends
+     * the revocation request as JSON.
+     * spec-cite: intuit/oauth-jsclient `OAuthClient.prototype.revoke` and `_tokenRequestHeaders`
+     * (https://raw.githubusercontent.com/intuit/oauth-jsclient/e65c49b0fd1c5356ba24ddbbe910b8bc71b6f75f/src/OAuthClient.js,
+     * fetched 2026-11-06).
+     */
+    readonly revocationRequestBodyEncoding?: ProviderOAuth2RequestBodyEncoding;
     /**
      * Scopes the vendor's own catalogue entry asked for. An application may request FEWER (a subset of
      * these, once resolved), and an operation's `requiredScopes` is the finer statement. Kept because
@@ -829,7 +1216,8 @@ export interface ProviderRestOAuth2 {
      *
      * ## Why this exists: the token endpoint receives the application's client secret
      *
-     * The exchange POSTs `client_id` and the APPLICATION's `client_secret` to the resolved `tokenUrl`.
+     * The exchange sends `client_id` and the APPLICATION's `client_secret` to the resolved `tokenUrl`, in the body or in a
+     * Basic header ({@link ProviderRestOAuth2.tokenEndpointAuthMethod}); either way the host receives the secret.
      * Until 2026-09-12 every placeholder was answered from the connect-start request body, so where a
      * placeholder formed the HOST — Microsoft's `https://{cloud}/…/token`, Salesforce's
      * `https://{environment}/…`, Zoho's `https://accounts.{location}/…` — any user allowed to start a
@@ -980,6 +1368,12 @@ export interface ProviderRestOAuth2Audience {
     readonly hosts: {
         readonly values: readonly string[];
         readonly hostSuffixes?: readonly string[];
+        /**
+         * The most DNS labels a host may carry before one of `hostSuffixes`; absent, any number (#3640). The same bound,
+         * with the same meaning, as a host allowance's `hostSuffixMaxLabels`: declare it where the vendor documents its
+         * hosts as one shape (`<store>.myshopify.com`), so a token is never sent to a deeper name under the suffix.
+         */
+        readonly hostSuffixMaxLabels?: number;
     };
     /**
      * The scopes that mint a token for this audience, all of ONE resource. An entry may begin with
@@ -999,7 +1393,10 @@ export interface ProviderOAuth2AudienceSelection {
     readonly audience: ProviderRestOAuth2Audience;
     readonly primary: boolean;
 }
-/** 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 declare function providerOAuth2AudienceAdmitsHost(audience: ProviderRestOAuth2Audience, host: string): boolean;
 /**
  * The ONE audience whose hosts admit `host`, or `undefined` when none does. The declaration guarantees at most one
@@ -1096,6 +1493,74 @@ export declare enum ProviderOAuth2PkceSupport {
     /** The vendor refuses PKCE from a confidential client (Slack): neither is sent. */
     NOT_ACCEPTED = "NOT_ACCEPTED"
 }
+/**
+ * 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 declare enum 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.
+     */
+    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.
+     */
+    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.
+     */
+    PRIVATE_KEY_JWT = "private_key_jwt"
+}
+/**
+ * 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 declare enum 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.
+     */
+    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.
+     */
+    JSON = "JSON"
+}
 /**
  * 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}).
@@ -1112,6 +1577,40 @@ export declare enum ProviderOAuth2ScopeListDelimiter {
      */
     COMMA = "COMMA"
 }
+/**
+ * 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 declare function describeProviderOAuth2ClientAuthenticationDefects(oauth2: Pick<ProviderRestOAuth2, 'tokenEndpointAuthMethod' | 'tokenRequestBodyEncoding' | 'revocationRequestBodyEncoding' | 'rfc7009RevocationUrl'>): string[];
+/** A refresh refusal the vendor documents as a dead refresh token. See {@link ProviderRestOAuth2.refreshRefusals}. */
+export interface ProviderOAuth2RefreshRefusal {
+    /** The OAuth2 `error` code of the refusal. */
+    readonly error: string;
+    /** The `error_description` the refusal must carry, exactly, when the code alone is not specific to a dead token. */
+    readonly errorDescription?: string;
+}
+/**
+ * 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 declare function describeProviderOAuth2TokenRequestDefects(oauth2: Pick<ProviderRestOAuth2, 'codeExchangeParameters' | 'refreshRefusals'>): string[];
+/**
+ * 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 declare function providerOAuth2RefreshRefusalIsDeclared(oauth2: Pick<ProviderRestOAuth2, 'refreshRefusals'>, answer: {
+    readonly error: string;
+    readonly errorDescription?: string;
+}): boolean;
 /**
  * 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}.
@@ -1161,13 +1660,104 @@ export declare enum ProviderOAuth2ReportedFactSource {
      * answer names the account only inside the ID token (#2660).
      * spec-cite: OpenID Connect Core 1.0 §3.1.3.7, item 6.
      */
-    ID_TOKEN_CLAIMS = "id_token_claims"
+    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.
+     */
+    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.
+     */
+    USERINFO_RESPONSE = "userinfo_response"
+}
+/** What reading a {@link ProviderOAuth2ReportedAccountFact.responsePath} out of a vendor's answer found (#3397). */
+export declare enum ProviderReportedFactReadOutcome {
+    /** A non-empty string or a finite number stood at the path; `value` is its text. */
+    FOUND = "FOUND",
+    /** Nothing usable stood at the path: a missing key, a `null`, an object, an empty string. The fact is not reported. */
+    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.
+     */
+    SELECTION_NOT_SINGLE = "SELECTION_NOT_SINGLE"
+}
+/** The result of {@link readProviderReportedFactValue}. */
+export type ProviderReportedFactRead = {
+    readonly outcome: ProviderReportedFactReadOutcome.FOUND;
+    readonly value: string;
+} | {
+    readonly outcome: ProviderReportedFactReadOutcome.ABSENT;
+} | {
+    readonly outcome: ProviderReportedFactReadOutcome.SELECTION_NOT_SINGLE;
+    readonly segment: string;
+    readonly matched: number;
+};
+/** One step of a parsed {@link ProviderOAuth2ReportedAccountFact.responsePath}. */
+export interface ProviderReportedFactPathSegment {
+    /** The own property read at this step. */
+    readonly key: string;
+    /** Present on a SELECTION step: the property is an array, and the one element whose `field` reads as `equals` is kept. */
+    readonly select?: {
+        readonly field: string;
+        readonly equals: string;
+    };
 }
+/**
+ * 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 declare function parseProviderReportedFactPath(path: string): readonly ProviderReportedFactPathSegment[] | 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 declare function readProviderReportedFactValue(payload: unknown, path: string): ProviderReportedFactRead;
+/**
+ * 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 declare const PROVIDER_OAUTH2_REDIRECT_PROTOCOL_PARAMETERS: readonly string[];
 /** One vendor-reported account fact. See {@link ProviderRestOAuth2.reportedAccountFacts}. */
 export interface ProviderOAuth2ReportedAccountFact {
     /**
-     * Dot-path inside the fact's {@link source}: the token endpoint's JSON answer by default, or the claims of its
-     * `id_token`. A string or finite number there is the value.
+     * Dot-path inside the fact's {@link source}: the token endpoint's JSON answer by default, the claims of its
+     * `id_token`, or the userinfo endpoint's JSON answer. A string or finite number there is the value. A step may select
+     * ONE element of an array by a stated condition, `accounts[is_default=true].account_id` (#3397); zero or several
+     * matching elements report nothing and refuse the connect ({@link readProviderReportedFactValue}). For
+     * {@link ProviderOAuth2ReportedFactSource.AUTHORIZATION_REDIRECT_QUERY}, the redirect's query parameter name.
      */
     readonly responsePath: string;
     /** Where {@link responsePath} is read. Omitted, the token endpoint's JSON answer. */
@@ -1179,6 +1769,27 @@ export interface ProviderOAuth2ReportedAccountFact {
     readonly origin?: Extract<ProviderOAuth2EndpointHostAllowance, {
         readonly kind: ProviderOAuth2EndpointHostAllowanceKind.DECLARED_VALUES;
     }>;
+    /**
+     * Present when operations may place the value as ONE PATH SEGMENT (#3397): QuickBooks' `/v3/company/{realmId}/…`. An
+     * operation names the fact on a PATH parameter ({@link ProviderRestOperationParameter.connectionFact}) and the caller
+     * never supplies it. A JavaScript regular expression the WHOLE value must match (it is anchored for you), checked when
+     * the connection is made (a value that does not match, or no value, refuses the connect) and again on every call, as
+     * an origin is. A value that matches is still refused when it is `.` or `..` or holds a `/`, so it can never move the
+     * request to another path. Keep it as narrow as the vendor documents: `\d+` for a QuickBooks company id.
+     *
+     * Without this a vendor-reported fact fills nothing: what the vendor reported is not an answer the person gave, and
+     * only a declared shape keeps a value that would otherwise go unexamined out of a URL.
+     */
+    readonly pathSegmentPattern?: string;
+    /**
+     * `true` when the value may fill the base URL's `{<this fact's name>}` HOST placeholder (#3397), admitted against the
+     * REST contract's `baseUrlHostAllowances` entry for that name on every call: the same allowance, and the same
+     * resolver, that admit a host a person typed at connect. Needs a `DECLARED_VALUES` allowance under the fact's name.
+     * Never filled into an OAuth2 endpoint (authorize, token, revocation): those carry the client secret, and only the
+     * person's answers or the deployment fill them. An `origin` is the other way to address the account; a fact is one
+     * or the other.
+     */
+    readonly fillsBaseUrlHost?: true;
     /**
      * `true` when the inbound receiver routes the vendor's deliveries to an organization by this fact: Slack's
      * `team.id`, the workspace an event comes from (#2660). Such a fact may name ONE organization only, so an
@@ -1252,6 +1863,37 @@ export declare function providerOAuth2IdTokenRequirementHolds(requirement: Provi
  * the behavior is entirely unspecified").
  */
 export declare function describeProviderOAuth2IdTokenRequirementDefects(oauth2: Pick<ProviderRestOAuth2, 'idTokenRequirements' | 'scopes' | 'reportedAccountFacts' | 'idTokenIssuer'>): string[];
+/**
+ * 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 declare function providerReportedPathSegmentAdmits(pattern: string, value: string): boolean;
+/** The REST-contract slice {@link describeProviderOAuth2ReportedFactUseDefects} reads. */
+export interface ProviderReportedFactUseContract {
+    readonly baseUrl?: string;
+    readonly baseUrlConnectionFact?: string;
+    readonly baseUrlHostAllowances?: Readonly<Record<string, ProviderOAuth2EndpointHostAllowance>>;
+    readonly oauth2?: Pick<ProviderRestOAuth2, 'reportedAccountFacts' | 'connectionParameters'> & Partial<Pick<ProviderRestOAuth2, 'tokenUrl' | 'userInfoUrl'>>;
+}
+/**
+ * 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 declare function describeProviderOAuth2ReportedFactUseDefects(contract: ProviderReportedFactUseContract): string[];
 /** The values a whole-scope placeholder admits. See {@link ProviderRestOAuth2.scopeValueAllowances}. */
 export interface ProviderOAuth2ScopeValueAllowance {
     readonly values: readonly string[];
@@ -1421,6 +2063,24 @@ export type ProviderOAuth2EndpointHostAllowance = {
      * so `evilmy.salesforce.com` never matches `.my.salesforce.com`.
      */
     readonly hostSuffixes?: readonly string[];
+    /**
+     * The MOST DNS labels an admitted host may carry before its suffix (#3640); absent, any number. Applies to every
+     * entry of `hostSuffixes`, and only to them (an exact `values` entry is admitted as written).
+     *
+     * Declared only where the VENDOR documents the shape. Shopify does: a store host is exactly one label under
+     * `.myshopify.com` ("Confirm the `shop` parameter matches `^[a-zA-Z0-9][a-zA-Z0-9\-]*\.myshopify\.com$`"), so it
+     * declares `1`. Without the bound, a person answering `shop` with the full domain they see, `acme.myshopify.com`,
+     * composed `acme.myshopify.com.myshopify.com`: a host under the suffix that does not exist, which failed every
+     * request on DNS. (That answer is now also stripped to its handle, see `stripProviderHostAnswerTemplateSuffix`; the
+     * bound is what refuses `acme.evil.myshopify.com`, naming the expected form.)
+     * spec-cite: https://shopify.dev/docs/apps/build/authentication-authorization/access-tokens/authorization-code-grant —
+     * the `shop` parameter check, as quoted in the Shopify module's header (fetched 2026-11-10).
+     *
+     * Every place a suffix admits a host reads it, through `providerHostIsUnderSuffix`: the answer filled into an endpoint
+     * or base URL, the token-endpoint host description, the declined-value check. A positive integer, with at least one
+     * suffix (`describeProviderOAuth2EndpointHostAllowanceDefects`).
+     */
+    readonly hostSuffixMaxLabels?: number;
     /**
      * ORIGIN only: an admitted value must ALSO have the same origin as the deployment's configured base
      * URL (the REST contract's `baseUrl` / `baseUrlEnvVarName`) (#991 review F4).
@@ -1526,6 +2186,59 @@ export declare enum ProviderOAuth2EndpointTemplateDefect {
  * hyphen; 63 octets per label).
  */
 export declare const PROVIDER_OAUTH2_DNS_NAME_PATTERN: RegExp;
+/**
+ * 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 declare function providerHostIsUnderSuffix(host: string, suffix: string, maxLabels?: number): boolean;
+/** One declared host suffix with its label bound, as {@link providerHostSuffixesOverlap} compares them. */
+export interface ProviderHostSuffixBound {
+    readonly suffix: string;
+    /** At most this many DNS labels before the suffix; absent, unbounded. See {@link providerHostIsUnderSuffix}. */
+    readonly maxLabels?: number;
+}
+/**
+ * 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 declare function providerHostSuffixesOverlap(left: ProviderHostSuffixBound, right: ProviderHostSuffixBound): boolean;
+/**
+ * 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 declare function stripProviderHostAnswerTemplateSuffix(value: string, literalHostSuffix: string | undefined): string;
+/**
+ * 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 declare function describeProviderHostSuffixExpectedForm(suffix: string, maxLabels: number | undefined, answerExcludesSuffix: boolean): string;
+/**
+ * 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 declare function describeProviderHostSuffixMaxLabelsDefects(maxLabels: number | undefined, hostSuffixes: readonly string[] | undefined): string[];
 /**
  * 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