@wildo-ai/external-connectors-models 1.1.4 → 1.1.6

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

@@ -19,11 +19,35 @@
  * path template, where its parameters ride — and none of that is backend runtime. The arrow already
  * pointed this way, since this package has no dependency on the private backend and the private
  * backend depends on it.
+ *
+ * ## This is the ONLY description of a REST provider — two earlier ones were deleted
+ *
+ * `rest-api.external-connectors-models.schemas.ts` described REST providers twice over, and both
+ * descriptions are gone. Neither should come back beside this module.
+ *
+ * - **An OpenAPI-shaped operation layer** (`REST_API_OperationSpecSchema`,
+ *   `REST_API_OperationContextSchema`, `REST_API_OperationDefinition`, `API_Parameter*`,
+ *   `API_ContentType`) — deleted 2026-09-06 by #331. Ten exported symbols and zero code readers: a
+ *   provider that authored one compiled, shipped, and was invisible to every runtime.
+ * - **A profile / configuration / status triple** (`REST_API_Provider_Profile`,
+ *   `REST_API_Provider_Configuration`, `REST_APIProvider_StatusSchema`) — deleted 2026-09-12 (#18).
+ *   Its only reader was the `ExternalProvider_ExchangeProtocol` union, itself read by nothing but a
+ *   drift test pinning it to the enum, and deleted in the same change. Its `pagination.style` was an
+ *   anonymous `"offset" | "cursor" | "page" | "link"` restating {@link ProviderRestPaginationStyle}.
+ *
+ * WHERE a REST API lives and how it authenticates is the `rest` arm of the backend runtime contract
+ * (`@wildo-ai/external-connectors-private/backend`); WHAT can be called against it is
+ * {@link ProviderRestOperation}, executed by `ProviderOperationExecutorBackendService`. A second
+ * description of either is not a missing feature — it is the drift that makes an authoring surface
+ * untrustworthy, because an author cannot tell which of two shapes is the one that runs. If an
+ * OpenAPI document is ever read (a second mapper input), it feeds `ProviderRestOperation` like
+ * every other source.
  */
 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';
+/** @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 {
     /** Substituted into a `{token}` of the path template. Always required — a path cannot have a hole. */
@@ -41,7 +65,30 @@ export declare enum ProviderRestRequestBodyEncoding {
     FORM_URLENCODED = "form-urlencoded",
     MULTIPART = "multipart",
     /** A raw text body; `contentType` on the declaration says which media type is sent. */
-    TEXT = "text"
+    TEXT = "text",
+    /**
+     * Raw bytes (#367, folding #364) — an image, a PDF, a file upload a vendor takes as the whole body.
+     * `contentType` is REQUIRED, by the TEXT arm's rule: a body without its media type is not addressable.
+     * The input must supply a `Uint8Array` (a Node `Buffer` is one); nothing is converted into bytes here,
+     * because a string encoded under a guessed charset is exactly how an upload arrives corrupted.
+     */
+    BINARY = "binary"
+}
+/**
+ * How the vendor's ANSWER is read (#367, folding #364).
+ *
+ * The request side could already send TEXT and the transport could already read TEXT and NONE, while
+ * the operation declaration could only say JSON — so an operation against a `text/csv` export could be
+ * authored and then failed at runtime as `INVALID_JSON`, a contract-breach message for a declaration
+ * the contract had no way to state. This is the missing half of that asymmetry.
+ */
+export declare enum ProviderRestResponseDecoding {
+    /** Parse the body as JSON. The default, and what an absent `responseDecoding` means. */
+    JSON = "json",
+    /** Keep the body as text — a CSV export, an XML document. The operation's output is that string. */
+    TEXT = "text",
+    /** Read nothing — a write whose answer carries no information (a 204). The output is `undefined`. */
+    NONE = "none"
 }
 /**
  * How a listing operation continues. A HINT the caller reads, never something the executor acts
@@ -81,8 +128,20 @@ export interface ProviderRestOperationRequestBody {
      * by a declared parameter — the ordinary shape, and the reason parameters declare `from`.
      */
     readonly from?: string;
-    /** For `TEXT`: the media type actually sent (`text/csv`, `application/xml`). */
+    /** For `TEXT` and `BINARY`: the media type actually sent (`text/csv`, `application/pdf`). Required for both. */
     readonly contentType?: string;
+    /**
+     * A JSON body sent INSIDE one named property: `envelope: 'data'` sends `{ "data": { …the body… } }` (#333).
+     *
+     * Asana answers `data: Missing input` to a task whose fields arrive at the top level — its API reads
+     * every write from a `data` wrapper, which the source catalogue builds in its request helper and the
+     * transposer never saw. Declared here rather than modelled as a nested input, so the INPUT stays flat:
+     * the fields a person fills in, and the fields an `inputOptions` key names, are the fields they see.
+     *
+     * JSON only. Any other encoding with an envelope is refused by name when the request is compiled — a
+     * form, text or binary body has no property to wrap it in.
+     */
+    readonly envelope?: string;
 }
 /** Where the payload sits inside a response, and how a listing continues. */
 export interface ProviderRestOperationPagination {
@@ -95,6 +154,44 @@ export interface ProviderRestOperationPagination {
     /** CURSOR/LINK: dot-path in the RESPONSE carrying the next cursor or the next URL. */
     readonly nextPath?: string;
 }
+/**
+ * Where an input's CHOICES come from: another operation of the same provider, run through the SAME
+ * connection, whose answer lists the values a person may pick (#333).
+ *
+ * The shape every workflow product converged on, and deliberately not a value stored on the connection.
+ * A workspace, a project, a channel are choices WITHIN an account, made per call: Zapier fills a
+ * dynamic dropdown with "a live API call", Make fills a module field through an RPC that "must have the
+ * same connection", n8n's resource locator lists through the node's credentials, and the Activepieces
+ * source this catalogue is scraped from declares Asana's workspace as a required dropdown whose options
+ * are fetched with the connected account. A connection records only what the vendor REPORTED when it
+ * was authorized ({@link ProviderRestOAuth2.accountRefResponsePath}).
+ *
+ * Declaring an options source does not make the options operation reachable from a browser: it is its
+ * own operation, and `providers.browserOperations` must list it like any other.
+ *
+ * @example
+ * // Asana: a task's project is chosen from the projects of the chosen workspace.
+ * inputOptions: {
+ *   workspace: { operationId: 'list_workspaces', valuePath: 'gid', labelPath: 'name' },
+ *   project: { operationId: 'list_projects', valuePath: 'gid', labelPath: 'name', dependsOn: { workspace: 'workspace' } },
+ * }
+ */
+export interface ProviderRestOperationInputOptions {
+    /** The operation that lists the choices. Same provider; its output (after its own `resultPath`) must be an array. */
+    readonly operationId: string;
+    /** That operation's catalogue domain, when it differs from the one being called. */
+    readonly domain?: string;
+    /** Dot-path, inside each listed item, to the value the input receives (`gid`). */
+    readonly valuePath: string;
+    /** 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> }`.
+     * 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>>;
+}
 /**
  * A provider operation, hand-authored. The unit an application addresses:
  * `executeProviderOperation({ providerRef: 'slack', operationId: 'conversations.list', input })`.
@@ -138,14 +235,35 @@ export interface ProviderRestOperation {
      * value is in naming the fields a caller may rely on, not in policing the vendor.
      */
     readonly outputSchema?: z.ZodType;
-    /** Dot-path to the payload inside the response body. Absent = the body IS the payload. */
+    /**
+     * How the answer is read. Absent = `JSON`, so every operation authored before this field existed
+     * reads exactly as it did.
+     *
+     * It also sets the default `Accept` header — `application/json` for JSON, `*\/*` otherwise — which a
+     * declared `Accept` HEADER parameter overrides when a vendor needs a specific media type.
+     *
+     * Two combinations are refused by name when the request is compiled, because each describes a payload
+     * that cannot exist: `resultPath` beside `TEXT` or `NONE` (there is no structure to walk), and
+     * `outputSchema` beside `NONE` (there is nothing to parse). `outputSchema` beside `TEXT` is legal and
+     * validates the string.
+     */
+    readonly responseDecoding?: ProviderRestResponseDecoding;
+    /** Dot-path to the payload inside the response body. Absent = the body IS the payload. JSON answers only. */
     readonly resultPath?: string;
     readonly pagination?: ProviderRestOperationPagination;
     /**
-     * OAuth scopes (or vendor permission names) the credential must carry. DECLARED in S3a and not
-     * yet CHECKED: checking it needs the composed registry's view of the secrets contract, which is
-     * #329's. Recorded as owed rather than half-enforced — a check that silently passes is worse
-     * than no check.
+     * OAuth scopes (or vendor permission names) the credential must carry, as the exact strings the vendor
+     * grants. CHECKED before the request leaves (#979): `ProviderOperationExecutorBackendService` compares them
+     * with the scopes recorded on the spent grant and refuses with the missing ones named when any is absent.
+     * A grant that records no scopes (a pasted key, a vendor that does not echo `scope`) proceeds, and the
+     * call's audit row says the check could not be made — refusing there would break every such vendor.
+     *
+     * Until 2026-09-14 this said "declared and not checked"; checking needed the granted set on the grant,
+     * which the connected-accounts lane now stores. Two things not to confuse it
+     * with: `ProviderRestOAuth2.scopes` is the vendor's ADVISORY default set, and the wildo-cli
+     * `getProviderApiKey({ requiredScopes })` parameter is a list of secret-contract SLUGS — a
+     * different concept sharing the name, which no production caller feeds from this field. As of
+     * 2026-09-12 no generated provider declares it either.
      */
     readonly requiredScopes?: readonly string[];
     /**
@@ -159,6 +277,11 @@ export interface ProviderRestOperation {
     readonly idempotent?: boolean;
     /** 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}.
+     */
+    readonly inputOptions?: Readonly<Record<string, ProviderRestOperationInputOptions>>;
     /** Set when the vendor has deprecated it; the executor logs once per operation, never refuses. */
     readonly deprecated?: {
         readonly reason: string;
@@ -172,7 +295,28 @@ export interface ProviderRestOperationCatalogue {
     readonly domains: readonly string[];
     /** Keyed by `operationId`. */
     readonly operations: Readonly<Record<string, ProviderRestOperation>>;
+    /**
+     * Which package contributed an operation that the provider's OWN module does not declare, keyed by
+     * `operationId` (#1672). Absent on every catalogue a provider module loads itself; set only by the
+     * framework when it merges an opted-in AUGMENTATION into a provider it does not own.
+     *
+     * A catalogue value and not a property of the operation, on purpose: an operation declaration is the
+     * augmentation author's data, and a field the author could write would let a package claim to be
+     * somebody else. The merge refuses a loaded catalogue that already carries this field.
+     *
+     * Read by the operation executor, which writes the contributor into the `PROVIDER_OPERATION_CALL` audit
+     * row: a call spending a shared grant must say whose code declared the request it sent.
+     */
+    readonly augmentedBy?: Readonly<Record<string, ProviderRestOperationContributor>>;
+}
+/** The package that contributed an operation to a provider it does not own (#1672). */
+export interface ProviderRestOperationContributor {
+    /** The augmentation package's npm name, as its own manifest states it. */
+    readonly packageName: string;
+    /** The installed version of that package, as `wildo config sync` read it from the manifest. */
+    readonly packageVersion: string;
 }
+/** @wildo_source:part:end external-connectors.models.rest-operation-contract */
 /**
  * The lazy catalogue loader — the seam #330's host loader consumes (interface note on #331).
  *
@@ -205,9 +349,96 @@ export interface ProviderRestCallSemantics {
         /** Linear backoff base — attempt N waits `backoffMs * (N - 1)`. */
         readonly backoffMs: number;
     };
-    /** A local sliding-window ceiling; the call REFUSES when exhausted rather than queueing. */
+    /**
+     * This REF's share of its connection's allowance: a sliding-window ceiling counted for every call made
+     * through this ref, whichever account it spends (#1729).
+     *
+     * It is a CEILING UNDER the connection's own budgets ({@link ProviderRateBudgetDeclaration}, declared by
+     * the connection's base), never a statement of the vendor's limit: several refs of one shared connection
+     * each keep their own ceiling and all draw on the one vendor allowance together.
+     */
     readonly maxRequestsPerMinute?: number;
 }
+/** @wildo_source:part:start external-connectors.models.connection-rate-budgets facet:layer:shared facet:family:provider facet:audience:app-developer */
+/**
+ * WHOSE allowance a vendor counts a request against, under one connection (#1729).
+ *
+ * A connection is one application registration at the vendor (one OAuth client, one API project) — the
+ * base provider's, however many refs spend it. Vendors meter on two axes of it, and a provider declares the
+ * one each of its limits uses:
+ *
+ * | vendor wording | member |
+ * |---|---|
+ * | Microsoft Graph "per app across all tenants"; Google "per minute per project" | {@link CONNECTION} |
+ * | Google "per minute per user per project"; Dataverse "for each user"; Graph "per app per tenant" / "per app and mailbox" when the grant owner IS that tenant or mailbox | {@link OWNER} |
+ *
+ * spec-cite: https://learn.microsoft.com/en-us/graph/throttling-limits — the global-limits table ("Per app across all
+ * tenants") and the scope list "per app across all tenants, per tenant for all apps, per app per tenant"; and
+ * https://developers.google.com/workspace/drive/api/guides/limits — "per minute per project" / "per minute per user per
+ * project". Fetched 2026-09-28.
+ *
+ * Deliberately NOT a member: "per tenant for all apps" (Graph). It counts OTHER applications' calls, which this
+ * deployment cannot see, so no local counter can hold it; the vendor's `429` is the only honest signal there.
+ */
+export declare enum ProviderRateBudgetPartition {
+    /** One allowance for the whole connection — every ref, every account it acts for, every process. */
+    CONNECTION = "connection",
+    /** One allowance per account the connection acts for — the grant's owner (a person, an organization, the deployment). */
+    OWNER = "owner"
+}
+/**
+ * One limit a vendor publishes, as the connection's BASE provider declares it (#1729).
+ *
+ * Read only from the connection's base: a member ref's declaration is inert, exactly like a member's OAuth client,
+ * because the limit belongs to the registration and the base owns the registration. Declared on the REST contract
+ * (`rest.rateBudgets`) for a connection whose tokens serve one resource, and on each OAuth2 AUDIENCE
+ * (`oauth2.audiences.<id>.rateBudgets`) for a connection spanning several — Microsoft Graph and a Dataverse
+ * environment are metered by different services with different numbers, so one list for both would be wrong for one.
+ *
+ * Counted by the engine BEFORE a request leaves: a call waits for room (bounded, see the executor's
+ * `rateBudgetWaitMs`) instead of spending a request the vendor would answer with `429`. The window is SLIDING, which
+ * is at least as strict as a vendor's fixed window of the same length.
+ */
+export interface ProviderRateBudgetDeclaration {
+    /** How many requests the window admits. */
+    readonly maxRequests: number;
+    /** The window's length, in seconds, as the vendor states it (Graph's global limit is per 10 s, Dataverse's per 300 s). */
+    readonly windowSeconds: number;
+    /** Whose allowance it is — see {@link ProviderRateBudgetPartition}. */
+    readonly partition: ProviderRateBudgetPartition;
+}
+/**
+ * Where a budget was COUNTED, as the call that spent it observed (#1729): `shared` when the deployment's shared store
+ * (Redis) counted it for every process of the application — backend replicas, minions, workers — and `process` when
+ * only this process did, because no shared store is configured here or it did not answer. Recorded on the call's audit
+ * row, so a per-process count is visible rather than implied.
+ */
+export declare enum RateBudgetCounting {
+    SHARED = "shared",
+    PROCESS = "process"
+}
+/**
+ * The defects of a connection's rate-budget declarations: a non-positive number, and a contract-level list beside
+ * `oauth2.audiences` — which would apply to nothing, since every call of such a connection is on one audience. A pure
+ * function so the registry refuses it at boot and a test pins it without a host.
+ */
+export declare function describeProviderRateBudgetDefects(input: {
+    readonly contractRateBudgets?: readonly ProviderRateBudgetDeclaration[];
+    readonly audiences?: Readonly<Record<string, {
+        readonly rateBudgets?: readonly ProviderRateBudgetDeclaration[];
+    }>>;
+}): string[];
+/**
+ * The declarations that apply to one call: the audience's own when the call's token is for an audience, else the
+ * contract's. Nothing is inherited between the two — see {@link describeProviderRateBudgetDefects}.
+ */
+export declare function selectProviderRateBudgetDeclarations(input: {
+    readonly contractRateBudgets?: readonly ProviderRateBudgetDeclaration[];
+    readonly audience?: {
+        readonly rateBudgets?: readonly ProviderRateBudgetDeclaration[];
+    };
+}): readonly ProviderRateBudgetDeclaration[];
+/** @wildo_source:part:end external-connectors.models.connection-rate-budgets */
 /**
  * A provider whose credential is MINTED by an authorization-code exchange rather than pasted.
  *
@@ -239,11 +470,81 @@ export interface ProviderRestOAuth2 {
     /** Where an authorization code (or a refresh token) is exchanged for an access token. */
     readonly tokenUrl: string;
     /**
-     * Scopes the vendor's own catalogue entry asked for. Advisory rather than enforced: an application
-     * may need fewer, and an operation's `requiredScopes` is the finer statement. Kept because it is
-     * the only record of what the vendor expects for the operations transposed beside it.
+     * Where a token is handed back to the vendor so the GRANT ends there too (#545).
+     *
+     * Deleting our copy of a token stops US using it. It does not stop the token working, and a
+     * refresh token frequently never expires on its own — so without this, "Disconnect" leaves the
+     * application listed in the person's own connected-apps screen at the vendor, and their belief
+     * that they have withdrawn access is not quite true.
+     *
+     * ## Why the field names RFC 7009 rather than "revocation"
+     *
+     * The name is the CONTRACT, not decoration. A URL here is POSTed
+     * `application/x-www-form-urlencoded` with a `token` parameter and an optional
+     * `token_type_hint`, and a 200 means the grant is gone — including for a token the server does
+     * not recognise.
+     * spec-cite: RFC 7009 §2.1 (revocation request) and §2.2 (revocation response), fetched
+     * 2026-09-18 — §2.2: *"The authorization server responds with HTTP status code 200 if the token
+     * has been revoked successfully or if the client submitted an invalid token"*, and *"invalid
+     * tokens do not cause an error response since the client cannot handle such an error in a
+     * reasonable way."*
+     *
+     * That last sentence is why the caller is best-effort and never branches on the body: there is
+     * nothing to branch on.
+     *
+     * **A vendor whose revocation is NOT RFC 7009 declares nothing here, deliberately.** Slack's
+     * `auth.revoke` is a Web API method and GitHub's is `DELETE /applications/{client_id}/token` with
+     * basic auth and a JSON body; neither is expressible as this URL, and bending the field to fit
+     * them would make a declaration that names RFC 7009 and means something else entirely. Those vendors
+     * need a per-vendor revocation ACTION, which is a bigger surface and is not built on speculation —
+     * until then the honest answer is an absent field, and the disconnect surface says so.
+     *
+     * Absent — not empty — when no revocation is declared, so "this vendor cannot be told" stays
+     * distinguishable from "nobody has looked".
+     */
+    readonly rfc7009RevocationUrl?: string;
+    /**
+     * 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
+     * it is the only record of what the vendor expects for the operations transposed beside it.
+     *
+     * ## A scope may carry a placeholder, and it is resolved like an endpoint's (#991)
+     *
+     * Two shapes exist, classified by {@link classifyProviderOAuth2ScopePlaceholder}:
+     *
+     * - `{hostUrl}/.default` — the placeholder BEGINS the scope and is followed by `/`, so its value is
+     *   an ORIGIN (Microsoft Dataverse names the resource a token is minted FOR by the environment URL).
+     *   It is filled only within {@link endpointHostAllowances}, exactly like an origin in an endpoint:
+     *   a caller-chosen resource would have the vendor mint a token for a host nobody declared.
+     * - `{permissions}` — the placeholder IS the whole scope entry, and its value is one or more scope
+     *   tokens chosen from {@link scopeValueAllowances}. Such a value can itself name a resource
+     *   (`https://graph.microsoft.com/.default`), so it is a closed choice, never free text.
+     *
+     * Any other placement (`api://{x}`, `{a}{b}`, `{x}.default`) is refused as malformed.
      */
     readonly scopes?: readonly string[];
+    /**
+     * How this vendor lets an EXISTING grant grow by one permission (#1671) — declared by the provider module that
+     * owns the OAuth client, never guessed by the engine. See {@link ProviderOAuth2IncrementalConsent}.
+     *
+     * Absent means the vendor's behaviour is not recorded, so a re-authorization for a missing scope RESTATES what the
+     * grant already holds beside the addition: an ordinary authorization that replaces the previous one, which every
+     * RFC 6749 server honours. Declared, the re-authorization asks for the missing scope only and the stored granted
+     * set ACCUMULATES the previous consent with the new answer.
+     */
+    readonly incrementalConsent?: ProviderOAuth2IncrementalConsent;
+    /**
+     * Scopes a person cannot grant for themselves: only an administrator of the account can (#1671). Microsoft's
+     * application permissions and its admin-restricted delegated permissions are the case — "Application permissions
+     * always require admin consent", and a delegated permission that requires admin consent answers a user with "an
+     * 'unauthorized to consent' error".
+     * spec-cite: https://learn.microsoft.com/en-us/entra/identity-platform/consent-types-developer — "Admin Consent for
+     * Application permissions" and "Admin Consent for Delegated Permissions", fetched 2026-09-27.
+     *
+     * Never put in a re-authorization request a person is sent to: an operation needing one is refused with the
+     * statement that an administrator must grant it, which is the only thing the person can act on.
+     */
+    readonly administratorConsentScopes?: readonly string[];
     /**
      * Env-var names resolving the APPLICATION's registration with the vendor. These are the two values
      * an operator genuinely does paste — they identify the integration, not the end user — and they
@@ -252,12 +553,13 @@ export interface ProviderRestOAuth2 {
     readonly clientIdSecretRef?: string;
     readonly clientSecretSecretRef?: string;
     /**
-     * Placeholders the endpoints above carry, which a CONNECTION must supply before either URL is a
-     * URL at all — `{cloud}`, `{tenantId}`, `{region}`, `{domain}`.
+     * Placeholders the endpoints above carry, which a CONNECTION must answer before either URL is a
+     * URL at all — `{cloud}`, `{tenantId}`, `{region}`, `{domain}`. A PATH placeholder is answered freely;
+     * a HOST or ORIGIN one only from {@link ProviderRestOAuth2.endpointHostAllowances}.
      *
-     * Measured over the transposed catalogue on 2026-09-08: of the 96 vendors that recovered both
-     * endpoints, **21 carry at least one placeholder**, led by `{cloud}` (18), `{location}` (10) and
-     * `{tenantId}` (6). Microsoft's authorize URL is
+     * Re-measured over the generated catalogue on 2026-09-12: of the 99 vendors that recovered both
+     * endpoints, **20 carry at least one placeholder**, led by `{cloud}` (18 occurrences), `{location}`
+     * (10) and `{tenantId}` (6). Microsoft's authorize URL is
      * `https://{cloud}/{tenantId}/oauth2/v2.0/authorize`, and no amount of application configuration
      * supplies those: which Azure cloud and which directory are facts about the ACCOUNT BEING
      * CONNECTED, known only to the person connecting it.
@@ -274,9 +576,554 @@ export interface ProviderRestOAuth2 {
      * Deliberately NOT a judgement about which connections a provider admits. That is a recorded
      * decision in the catalogue record and is never read from a vendor's API surface; this is a
      * mechanical fact about a string.
+     *
+     * A placeholder filled from {@link ProviderOAuth2EndpointHostAllowanceKind.DEPLOYMENT_BASE_URL} or
+     * {@link ProviderOAuth2EndpointHostAllowanceKind.DEPLOYMENT_CONFIGURED} is NOT listed: nobody
+     * connecting an account is asked for it, and a value they supply is refused.
+     *
+     * Derived from the {@link scopes} as well as the endpoints (#991): Dataverse's `{hostUrl}/.default`
+     * names a fact about the account (its environment URL) that no endpoint carries, and a placeholder
+     * only a scope mentions was otherwise never asked for — so the authorize request carried the literal
+     * brace to the vendor.
      */
     readonly connectionParameters?: readonly string[];
+    /**
+     * How each placeholder that forms an endpoint's HOST or ORIGIN may be filled, keyed by
+     * placeholder name. A host/origin placeholder with NO entry here cannot be filled at all, and the
+     * connect flow refuses it.
+     *
+     * ## 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`.
+     * 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
+     * connection chose where that secret was sent (`cloud=attacker.tld`). Measured over the generated
+     * catalogue that day: 34 host-position occurrences across 17 vendors (9 Microsoft, 6 Zoho,
+     * Salesforce, Workday), plus two whole-origin
+     * placeholders (`gitea`, `bigin-by-zoho`) that were safe only because percent-encoding made them
+     * undialable (#623).
+     *
+     * So a host/origin value is chosen from what the PROVIDER declares, never from what a caller
+     * types. Path and query placeholders (`{tenantId}`, Workday's `{tenant}`) stay free and are
+     * percent-encoded, because an encoded path segment cannot move the request to another host.
+     *
+     * Derived by the transposer where the source catalogue states a closed choice (a dropdown), and
+     * otherwise taken from a recorded human decision in the catalogue record — never guessed.
+     *
+     * Also governs a placeholder that forms the ORIGIN of a SCOPE (`{hostUrl}/.default`, #991). One
+     * allow-list per placeholder name, wherever the name forms a host: a scope's resource URI decides
+     * which host the vendor mints the token for, which is the same question an endpoint's host answers.
+     */
+    readonly endpointHostAllowances?: Readonly<Record<string, ProviderOAuth2EndpointHostAllowance>>;
+    /**
+     * The closed set of values a WHOLE-SCOPE placeholder (`scopes: ['{permissions}']`) may be answered
+     * with, keyed by placeholder name (#991).
+     *
+     * Each value is substituted verbatim as that scope entry and may hold several space-delimited scope
+     * tokens — Microsoft Entra ID's permission presets are one such string each. Matched exactly, because
+     * scope values are case-sensitive.
+     * spec-cite: RFC 6749 §3.3 (the scope parameter is a list of space-delimited, case-sensitive strings).
+     *
+     * Closed rather than free because a scope value can itself name a resource
+     * (`https://graph.microsoft.com/.default`), and a whole-scope placeholder with NO entry here cannot be
+     * answered at all. Derived by the transposer from the source's own dropdown; never guessed.
+     */
+    readonly scopeValueAllowances?: Readonly<Record<string, ProviderOAuth2ScopeValueAllowance>>;
+    /**
+     * Dot-path, inside the TOKEN ENDPOINT'S JSON answer, to the vendor's own identifier for the account
+     * that was just authorized — Slack's `team.id` (#333).
+     *
+     * Read once, at the exchange, into the stored grant's `accountRef`, so a person holding two
+     * connections to one vendor can tell which is which and the grant audit names the account. Absent
+     * means the vendor reports no account identity in its token answer (Asana's names only the user).
+     *
+     * Identity only: nothing looks a credential up by it, and an answer that lacks the path stores the
+     * grant without it — a missing label is not a reason to discard an authorization the person just gave.
+     */
+    readonly accountRefResponsePath?: string;
+    /**
+     * Facts about the connected ACCOUNT that the vendor reports in its token answer and OPERATIONS consume,
+     * keyed by the fact's name (#333, #1047) — Salesforce's `instance_url`, Pipedrive's `api_domain`.
+     *
+     * Captured at the authorization-code exchange and again at every refresh, into the credential row's
+     * `connectionFacts` with provenance `REPORTED_BY_VENDOR`. Distinct from {@link accountRefResponsePath}:
+     * that is a LABEL a person reads, sealed in the grant; these are values requests are built from, kept
+     * client-readable beside the answers a person typed at connect.
+     *
+     * A fact that carries an `origin` allowance is an https ORIGIN operations may dial, so it decides where a
+     * request carrying the credential goes. It is therefore admitted exactly as an ORIGIN placeholder is
+     * ({@link endpointHostAllowances}): refused at connect when absent or outside the allowance, and
+     * re-checked on every call that uses it.
+     */
+    readonly reportedAccountFacts?: Readonly<Record<string, ProviderOAuth2ReportedAccountFact>>;
+    /**
+     * The RESOURCE AUDIENCES one grant of this client can mint tokens for, keyed by audience id (#1725), and the
+     * HOSTS a token of each may be sent to.
+     *
+     * ## Why a grant needs more than one access token
+     *
+     * Microsoft issues an access token for ONE resource per request: the token redemption's scopes "must all be from a
+     * single resource", and a refresh request spanning several resources returns "a token for the resource specified
+     * in the first scope". A refresh token, though, is not tied to a resource: "A client can use a refresh token to
+     * acquire access tokens across any combination of resource and tenant where it has permission to do so." So a
+     * connection spanning Graph and Dataverse keeps ONE refresh token and mints a token per audience from it.
+     * spec-cite: https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow — the `scope` rows
+     * of "Redeem a code for an access token" and "Refresh the access token"; and
+     * https://learn.microsoft.com/en-us/entra/identity-platform/refresh-tokens — the opening section. Fetched 2026-09-27.
+     *
+     * ## Why the HOSTS are part of the declaration
+     *
+     * An access token is a bearer credential for its resource. Declaring which hosts receive a token of each audience is
+     * what lets the engine attach a token only to a request bound for its own resource (the token-host binding), so an
+     * operation — the base's own, a member's, or an augmentation's (#1672) — can never carry a Graph token to another
+     * host.
+     *
+     * Absent means the provider mints one token for one resource, which is every provider except a connection base that
+     * spans several. When present, {@link primaryAudience} names the audience the AUTHORIZATION grants — the resource of
+     * the connect request's scopes — whose token is the one stored with the grant; every other audience's token is minted
+     * from the refresh token on demand and cached, never stored.
+     */
+    readonly audiences?: Readonly<Record<string, ProviderRestOAuth2Audience>>;
+    /** The audience the authorization itself grants — see {@link audiences}. Required when `audiences` is declared. */
+    readonly primaryAudience?: string;
+}
+/** @wildo_source:part:start external-connectors.models.oauth2-audiences facet:layer:shared facet:family:provider facet:audience:app-developer */
+/** The placeholder a {@link ProviderRestOAuth2Audience.mintScopes} entry uses for the https origin of the request's host. */
+export declare const PROVIDER_OAUTH2_AUDIENCE_ORIGIN_PLACEHOLDER = "{audienceOrigin}";
+/** One resource audience of a connection's grant. See {@link ProviderRestOAuth2.audiences}. */
+export interface ProviderRestOAuth2Audience {
+    /**
+     * The hosts a token of this audience may be sent to: exact lower-case hosts, and dotted suffixes admitting
+     * `<dns-labels><suffix>` (never the bare suffix). Every host is https.
+     */
+    readonly hosts: {
+        readonly values: readonly string[];
+        readonly hostSuffixes?: readonly string[];
+    };
+    /**
+     * The scopes that mint a token for this audience, all of ONE resource. An entry may begin with
+     * {@link PROVIDER_OAUTH2_AUDIENCE_ORIGIN_PLACEHOLDER} — the https origin of the request's own host, admitted by
+     * {@link hosts} first — for a resource named per customer (a Dataverse environment's `<environment-url>/.default`).
+     */
+    readonly mintScopes: readonly string[];
+    /**
+     * The vendor's published limits for THIS resource (#1729) — see {@link ProviderRateBudgetDeclaration}. Per audience
+     * because each resource is metered by its own service: Graph's limits say nothing about a Dataverse environment.
+     */
+    readonly rateBudgets?: readonly ProviderRateBudgetDeclaration[];
+}
+/** The audience a request host belongs to, with its id — see {@link selectProviderOAuth2AudienceForHost}. */
+export interface ProviderOAuth2AudienceSelection {
+    readonly id: string;
+    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. */
+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
+ * ({@link describeProviderOAuth2AudienceDefects} refuses overlapping hosts), so the answer never depends on order.
+ */
+export declare function selectProviderOAuth2AudienceForHost(oauth2: Pick<ProviderRestOAuth2, 'audiences' | 'primaryAudience'>, host: string): ProviderOAuth2AudienceSelection | undefined;
+/**
+ * The scopes that mint `audience`'s token for a request to `origin` — `{audienceOrigin}` replaced by that origin.
+ * The caller has already admitted the origin's host through {@link selectProviderOAuth2AudienceForHost}; nothing a
+ * caller supplies reaches a scope any other way.
+ */
+export declare function resolveProviderOAuth2AudienceMintScopes(audience: ProviderRestOAuth2Audience, origin: string): readonly string[];
+/**
+ * The declared audience a scope a connection might REQUEST names (#1671): its id, or `undefined` when the scope names a
+ * resource none of the connection's audiences covers. Only meaningful when `audiences` is declared.
+ *
+ * A scope that is an absolute URI names the resource a token is minted for (`https://graph.microsoft.com/Mail.Send`,
+ * `https://contoso.crm.dynamics.com/user_impersonation`): the resource of one of an audience's fixed mint scopes (the
+ * mint scope without its last path segment), or — for a mint scope beginning `{audienceOrigin}` — an https origin whose
+ * host the audience admits. A scope that is not an absolute URI (`offline_access`, `Files.Read`) names no resource, and
+ * the vendor reads it against its default one, the PRIMARY audience: "omitting the resource identifier in the `scope`
+ * parameter defaults to Microsoft Graph".
+ * spec-cite: https://learn.microsoft.com/en-us/entra/identity-platform/consent-types-developer — the note under
+ * "Admin Consent for Delegated Permissions", fetched 2026-09-27.
+ */
+export declare function findProviderOAuth2ScopeAudience(oauth2: Pick<ProviderRestOAuth2, 'audiences' | 'primaryAudience'>, scope: string): string | undefined;
+/**
+ * Whether a scope a connection might REQUEST names a resource among the connection's declared audiences (#1671) — see
+ * {@link findProviderOAuth2ScopeAudience}. Asking a person to consent to it is asking them to let this application reach
+ * THAT resource, so a scope from a member ref or an opted-in augmentation (#1672) is requestable only when it names one
+ * the connection declares. `true` without looking further when the connection declares no audiences: it mints one token
+ * for one resource and its scopes are the vendor's own vocabulary (Google's scope URIs name permissions, not resources).
+ */
+export declare function providerOAuth2ScopeNamesDeclaredAudience(oauth2: Pick<ProviderRestOAuth2, 'audiences' | 'primaryAudience'>, scope: string): boolean;
+/** @wildo_source:part:end external-connectors.models.oauth2-audiences */
+/** @wildo_source:part:start external-connectors.models.oauth2-incremental-consent facet:layer:shared facet:family:provider facet:audience:app-developer */
+/**
+ * How a vendor extends an existing delegated grant with more scopes — see {@link ProviderRestOAuth2.incrementalConsent}.
+ */
+export declare enum ProviderOAuth2IncrementalConsentForm {
+    /**
+     * The vendor keeps what the person already consented to, and a new authorization request naming only the added
+     * scopes ADDS them: Microsoft's delegated permissions "will be granted in addition to any other permissions that
+     * were already granted for that app (i.e. incremental)".
+     * spec-cite: https://learn.microsoft.com/en-us/entra/identity-platform/consent-types-developer — "Incremental and
+     * dynamic user consent", fetched 2026-09-27.
+     */
+    ADDITIVE = "ADDITIVE",
+    /**
+     * The vendor adds the new scopes to the existing grant only when the request carries `include_granted_scopes=true`:
+     * "If you set this parameter's value to `true` and the authorization request is granted, then the new access token
+     * will also cover any scopes to which the user previously granted the application access."
+     * spec-cite: https://developers.google.com/identity/protocols/oauth2/web-server#incrementalAuth — the
+     * `include_granted_scopes` parameter row, fetched 2026-09-27.
+     */
+    INCLUDE_GRANTED_SCOPES = "INCLUDE_GRANTED_SCOPES"
+}
+/** A vendor's incremental-consent behaviour. See {@link ProviderRestOAuth2.incrementalConsent}. */
+export interface ProviderOAuth2IncrementalConsent {
+    readonly form: ProviderOAuth2IncrementalConsentForm;
+    /**
+     * Scopes every re-authorization request repeats beside the added ones — protocol scopes the answer needs rather than
+     * permissions (Microsoft's `offline_access`, without which a code redemption returns no refresh token). Each must be
+     * among the provider's declared {@link ProviderRestOAuth2.scopes}.
+     */
+    readonly restatedScopes?: readonly string[];
+}
+/** @wildo_source:part:end external-connectors.models.oauth2-incremental-consent */
+/**
+ * Why a declared audience set cannot be honoured, or an empty list. Checked where a provider is composed, so a
+ * malformed declaration never reaches a request:
+ * - `primaryAudience` names no declared audience, or is missing while audiences are declared;
+ * - the primary audience's mint scopes are not among the authorization's own `scopes` (its token is the one the
+ *   code redemption returns, so the authorization must be FOR that resource) or use the origin placeholder;
+ * - an audience with no host or no mint scope, a suffix without a leading dot, an origin placeholder anywhere but
+ *   the start of a scope, or any other `{placeholder}` in a mint scope;
+ * - two audiences admitting one host — a request host must select exactly one token.
+ */
+export declare function describeProviderOAuth2AudienceDefects(oauth2: Pick<ProviderRestOAuth2, 'audiences' | 'primaryAudience' | 'scopes'>): string[];
+/** One vendor-reported account fact. See {@link ProviderRestOAuth2.reportedAccountFacts}. */
+export interface ProviderOAuth2ReportedAccountFact {
+    /** Dot-path inside the token endpoint's JSON answer. A string or finite number there is the value. */
+    readonly responsePath: string;
+    /**
+     * Present when the value is an https ORIGIN operations dial. The same DECLARED_VALUES vocabulary an
+     * ORIGIN placeholder uses: exact origins, or `https://<dns-labels><suffix>` for each dotted suffix.
+     */
+    readonly origin?: Extract<ProviderOAuth2EndpointHostAllowance, {
+        readonly kind: ProviderOAuth2EndpointHostAllowanceKind.DECLARED_VALUES;
+    }>;
+}
+/** The values a whole-scope placeholder admits. See {@link ProviderRestOAuth2.scopeValueAllowances}. */
+export interface ProviderOAuth2ScopeValueAllowance {
+    readonly values: readonly string[];
+    /** Values the vendor's source offers and the catalogue declines, matched exactly. See {@link ProviderOAuth2UnsupportedValues}. */
+    readonly unsupportedValues?: ProviderOAuth2UnsupportedValues;
+}
+/**
+ * Values the vendor's OWN source offers for a placeholder and this catalogue deliberately does NOT admit, each mapped
+ * to the reason (#1937). Keyed by the value as the source writes it.
+ *
+ * Not a second allow-list: the admitted set (`values`, `hosts`) alone decides what is admitted, and a value found
+ * here is refused exactly as any other unadmitted value is (`VALUE_NOT_ADMITTED`, which also retires a STORED
+ * connection that carries it). What this adds is the WHY. A person who chose, or a connection that stored, a value
+ * the catalogue declined is told that it is unsupported and for what reason, instead of being handed a list of other
+ * values as though they had made a typing mistake.
+ *
+ * The first entry is the US Government Microsoft clouds (`login.microsoftonline.us`, GCC High and DoD), declared out
+ * of scope by product decision on 2026-09-29. The transposer writes these from the vendor record's declared
+ * exclusion (`_code_archive/providers/catalogue-record/vendors/<vendor>.json` since #2019 archived the catalogue; a
+ * registry provider adopted from it states them in its own module under `providers-registry/<ref>/`), so reversing a
+ * decision is record edits and a regeneration, never an engine change. How many edits depends on what the decline also removed: for the US
+ * Government clouds, three (the catalogue README lists them).
+ */
+export type ProviderOAuth2UnsupportedValues = Readonly<Record<string, string>>;
+/** How a placeholder's value is compared with a declared one. */
+export declare enum ProviderOAuth2ValueComparison {
+    /** A host or an origin: DNS names compare case-insensitively. spec-cite: RFC 4343 §2. */
+    CASE_INSENSITIVE = "CASE_INSENSITIVE",
+    /** A scope value: scope strings are case-sensitive. spec-cite: RFC 6749 §3.3. */
+    EXACT = "EXACT"
+}
+/**
+ * The declared reason a value is unsupported, or `undefined` when it is not declared unsupported. Compared as the
+ * placeholder's values are: case-insensitively for a host or origin, exactly for a scope value.
+ */
+export declare function findProviderOAuth2UnsupportedValueReason(unsupportedValues: ProviderOAuth2UnsupportedValues | undefined, value: string, comparison: ProviderOAuth2ValueComparison): string | undefined;
+/**
+ * Where a `{placeholder}` sits inside one OAuth2 SCOPE entry. See {@link classifyProviderOAuth2ScopePlaceholder}.
+ *
+ * Deliberately not {@link ProviderOAuth2EndpointPlaceholderPosition}: a scope is not a URL, and the
+ * endpoint scan would call `{permissions}` an ORIGIN (it begins the string and nothing follows it).
+ */
+export declare enum ProviderOAuth2ScopePlaceholderPosition {
+    /**
+     * The placeholder begins the scope and is followed by `/` — `{hostUrl}/.default`. Its value is an
+     * https ORIGIN, admitted only within {@link ProviderRestOAuth2.endpointHostAllowances}.
+     */
+    ORIGIN = "ORIGIN",
+    /**
+     * The placeholder is the entire scope entry — `{permissions}`. Its value is one of
+     * {@link ProviderRestOAuth2.scopeValueAllowances}.
+     */
+    WHOLE_SCOPE = "WHOLE_SCOPE"
+}
+/** Why a scope entry cannot be resolved safely, whatever is supplied. See {@link findProviderOAuth2ScopeTemplateDefects}. */
+export declare enum ProviderOAuth2ScopeTemplateDefect {
+    /**
+     * A placeholder sits anywhere except at the start of the scope followed by `/` or the end —
+     * `api://{x}/.default`, `{x}.default`, `openid {x}`. Such a value would be concatenated with text
+     * around it into a resource or scope nobody declared.
+     */
+    UNSUPPORTED_PLACEHOLDER_POSITION = "UNSUPPORTED_PLACEHOLDER_POSITION",
+    /** More than one placeholder in one scope entry: each value validated alone can compose an undeclared one. */
+    SEVERAL_PLACEHOLDERS = "SEVERAL_PLACEHOLDERS",
+    /** A `{` or `}` that is not part of a well-formed placeholder: a vendor can never grant a scope carrying one. */
+    STRAY_BRACE = "STRAY_BRACE"
+}
+/** One `{placeholder}` in a scope entry. */
+export interface ProviderOAuth2ScopePlaceholderOccurrence {
+    readonly name: string;
+    readonly position: ProviderOAuth2ScopePlaceholderPosition;
+    /** The whole `{name}` token, for substitution. */
+    readonly token: string;
+}
+/**
+ * The defects that make a scope entry unsafe to resolve, or an empty list. Shared by the runtime (which
+ * refuses) and the transposer (which refuses to emit), so neither admits a shape the other rejects.
+ */
+export declare function findProviderOAuth2ScopeTemplateDefects(scope: string): readonly ProviderOAuth2ScopeTemplateDefect[];
+/**
+ * Classify the one placeholder a scope entry may carry, or `undefined` when it carries none.
+ *
+ * ONE function, shared by the transposer and the runtime, like its endpoint counterpart. Meaningful only
+ * for a scope with no {@link findProviderOAuth2ScopeTemplateDefects}; every consumer refuses those first.
+ */
+export declare function classifyProviderOAuth2ScopePlaceholder(scope: string): ProviderOAuth2ScopePlaceholderOccurrence | undefined;
+/**
+ * Why a declared whole-scope allowance cannot be applied, or an empty list. Enforced at generation so a
+ * broken set refuses the batch; the runtime matches exactly and never trusts a value it did not declare.
+ */
+export declare function describeProviderOAuth2ScopeValueAllowanceDefects(allowance: ProviderOAuth2ScopeValueAllowance): readonly string[];
+/**
+ * Where a `{placeholder}` sits inside an OAuth2 endpoint template — the classification the host
+ * allow-list keys on. See {@link classifyProviderOAuth2EndpointPlaceholders}.
+ */
+export declare enum ProviderOAuth2EndpointPlaceholderPosition {
+    /**
+     * The placeholder BEGINS the template, so its value is the whole scheme + authority (+ any path
+     * prefix): `{baseUrl}/login/oauth/authorize`. The most dangerous position — the value names the
+     * scheme as well as the host.
+     */
+    ORIGIN = "ORIGIN",
+    /**
+     * The placeholder sits between `://` and the first `/`, `?` or `#` after it:
+     * `https://{cloud}/common/…`, `https://accounts.{location}/…`. Its value decides which host
+     * receives the request.
+     */
+    HOST = "HOST",
+    /** Anywhere after the authority. Percent-encoded, so it cannot move the request to another host. */
+    PATH_OR_QUERY = "PATH_OR_QUERY"
+}
+/** How a host- or origin-forming placeholder may be filled. See {@link ProviderRestOAuth2.endpointHostAllowances}. */
+export declare enum ProviderOAuth2EndpointHostAllowanceKind {
+    /**
+     * Chosen at connect time from values the provider DECLARES — Microsoft's commercial login cloud,
+     * Zoho's data centres. A value outside the set is refused; a declared value is substituted
+     * verbatim (it is a hostname or origin, not a path segment to encode).
+     *
+     * `hostSuffixes` additionally admits `<dns-label>(.<dns-label>)*` followed by one of the suffixes,
+     * for a vendor whose per-customer host is a subdomain it controls (Salesforce My Domain,
+     * `<name>.my.salesforce.com`). On a HOST placeholder a suffix applies only when the placeholder is
+     * the WHOLE host. On an ORIGIN placeholder it admits exactly `https://<dns-labels><suffix>` — the
+     * scheme fixed to https, no port, path, userinfo, query or fragment — which is what a per-customer
+     * origin such as a Dataverse environment URL (`https://<org>.crm4.dynamics.com`, #991) needs.
+     */
+    DECLARED_VALUES = "DECLARED_VALUES",
+    /**
+     * Filled from the DEPLOYMENT's configured base URL for this provider — the REST contract's
+     * `baseUrl`, or the environment variable its `baseUrlEnvVarName` names. For a self-hosted vendor
+     * (Gitea) the operator names the instance once; a person connecting an account is never asked, and
+     * a value they supply is refused. Admitted in the ORIGIN position only.
+     */
+    DEPLOYMENT_BASE_URL = "DEPLOYMENT_BASE_URL",
+    /**
+     * Filled from a deployment environment variable dedicated to THIS placeholder, named by the
+     * allowance's `envVarName` (#992). For a vendor whose endpoints sit on more than one per-tenant host
+     * — Workday's `https://{authHost}/…/authorize` and `https://{apiHost}/…/token` — one base URL cannot
+     * name both, so each host is its own operator setting (`WORKDAY_AUTH_HOST`, `WORKDAY_API_HOST`).
+     *
+     * Like DEPLOYMENT_BASE_URL, never asked of a person connecting, and a value they supply is refused.
+     * The trade is explicit: the application serves the one vendor tenant (data centre) the operator
+     * names. Admitted on a HOST placeholder that is the whole host, with a DNS-name value.
+     */
+    DEPLOYMENT_CONFIGURED = "DEPLOYMENT_CONFIGURED",
+    /**
+     * DERIVED from another connect-time answer through a declared table (#1937): Microsoft Graph's operation host follows
+     * the login cloud the connection chose (`login.microsoftonline.com` → `graph.microsoft.com`), because a token minted by
+     * one national cloud is not accepted by another. The Microsoft source also maps the US Government login cloud; that
+     * row is declined (`unsupportedValues`), because US Government clouds are out of scope (decision of 2026-09-29).
+     *
+     * Never asked of a person and never taken from a request: the value is looked up from the ANSWER the connection
+     * stored for `answer`, and an answer the table does not name is refused. `whenUnanswered` is the host for a connection
+     * that answered nothing (the application's own pasted credential); absent, such a connection is refused. The table is
+     * the allow-list, so no other host can result. Admitted on a HOST placeholder that is the whole host.
+     *
+     * spec-cite: https://learn.microsoft.com/en-us/graph/deployments — "Access tokens acquired for a national cloud
+     * deployment are not interchangeable with those acquired for the global service or any other national cloud."
+     */
+    DERIVED_FROM_CONNECTION_ANSWER = "DERIVED_FROM_CONNECTION_ANSWER"
+}
+export type ProviderOAuth2EndpointHostAllowance = {
+    readonly kind: ProviderOAuth2EndpointHostAllowanceKind.DECLARED_VALUES;
+    /** Exact admitted values, compared case-insensitively. A hostname for HOST, an origin for ORIGIN. */
+    readonly values: readonly string[];
+    /**
+     * A whole HOST, or an ORIGIN (admitting `https://<labels><suffix>` only). Each MUST begin with `.`,
+     * so `evilmy.salesforce.com` never matches `.my.salesforce.com`.
+     */
+    readonly hostSuffixes?: readonly string[];
+    /**
+     * 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).
+     *
+     * For a vendor whose token is minted for a per-customer environment and whose operations dial the
+     * operator's configured instance — Dataverse mints for the scope's `{hostUrl}` while operations go to
+     * `MICROSOFT_DYNAMICS_CRM_BASE_URL` — a connection naming another environment would hold a token that
+     * fails every call. So the two are required to agree at connect, and an unset base URL refuses the
+     * connect as a deployment gap rather than minting a token nothing can use.
+     */
+    readonly originMatchesDeploymentBaseUrl?: true;
+    /** Values the vendor's source offers and the catalogue declines, with the reason. See {@link ProviderOAuth2UnsupportedValues}. */
+    readonly unsupportedValues?: ProviderOAuth2UnsupportedValues;
+} | {
+    readonly kind: ProviderOAuth2EndpointHostAllowanceKind.DEPLOYMENT_CONFIGURED;
+    /**
+     * The deployment environment variable holding the host — derived by the transposer as
+     * `<PROVIDER_ENV_PREFIX>_<PLACEHOLDER_IN_SCREAMING_SNAKE>` and declared as a REGISTRATION secret slot,
+     * without which the runtime environment builder would strip it.
+     */
+    readonly envVarName: string;
+} | {
+    readonly kind: ProviderOAuth2EndpointHostAllowanceKind.DERIVED_FROM_CONNECTION_ANSWER;
+    /** The connect-time answer the host is derived from (`cloud`) — itself a placeholder of the same provider. */
+    readonly answer: string;
+    /** Per answer value (compared case-insensitively), the host it selects. DNS names. */
+    readonly hosts: Readonly<Record<string, string>>;
+    /** The host when the connection answered nothing; absent, an unanswered connection is refused. */
+    readonly whenUnanswered?: string;
+    /**
+     * ANSWER values the vendor's source maps to a host and the catalogue declines, with the reason — so a stored
+     * connection carrying one is refused at use naming why. See {@link ProviderOAuth2UnsupportedValues}.
+     */
+    readonly unsupportedValues?: ProviderOAuth2UnsupportedValues;
+} | {
+    readonly kind: ProviderOAuth2EndpointHostAllowanceKind.DEPLOYMENT_BASE_URL;
+    /**
+     * A path the configured base URL carries and the OAuth2 endpoints do NOT — stripped before
+     * substitution, and REQUIRED to be present. Gitea's operation base is `<instance>/api/v1` while
+     * its OAuth2 endpoints hang off `<instance>`; stripping keeps an instance served under a sub-path
+     * correct, where taking only the origin would drop it.
+     */
+    readonly baseUrlPathSuffix?: string;
+};
+/** One `{placeholder}` occurrence in an OAuth2 endpoint template. */
+export interface ProviderOAuth2EndpointPlaceholderOccurrence {
+    readonly name: string;
+    readonly position: ProviderOAuth2EndpointPlaceholderPosition;
+    /** Offset of the opening brace in the template. */
+    readonly index: number;
+    /** The whole `{name}` token, for substitution. */
+    readonly token: string;
+    /**
+     * HOST only: the token is the ENTIRE authority (`https://{cloud}/…`), as opposed to one part of it
+     * (`https://accounts.{location}/…`). A declared host SUFFIX is only meaningful for a whole host — on a
+     * partial one it would be concatenated with the text around it and admit a host nobody declared.
+     */
+    readonly occupiesWholeHost: boolean;
+    /**
+     * HOST only: when the token OPENS the authority and is followed by literal text up to the end of the authority —
+     * `https://{subdomain}.zendesk.com/…` → `.zendesk.com` — that literal text (#1015). A declared host SUFFIX equal to it
+     * bounds the composed host exactly as it bounds a whole host: the value is DNS labels, the template's own literal
+     * supplies the suffix, and `<labels>.zendesk.com` is the only shape that can result. Absent for a whole host, for a
+     * token that does not open the host (`accounts.{location}`), and for an ORIGIN or PATH token.
+     */
+    readonly literalHostSuffix?: string;
+}
+/**
+ * Why an OAuth2 endpoint TEMPLATE cannot be resolved safely, whatever values are supplied.
+ * See {@link findProviderOAuth2EndpointTemplateDefects}.
+ */
+export declare enum ProviderOAuth2EndpointTemplateDefect {
+    /**
+     * The template neither begins `http://` / `https://` nor begins with a placeholder. The WHATWG URL
+     * parser reads `https:/{h}/t`, `https:{h}/t` and `https:` + two backslashes + `{h}/t` as `https://h/t`, so a string scan
+     * for `://` would call `{h}` a PATH placeholder, encode it (a hostname survives encoding untouched),
+     * and send the request — and the client secret — to whatever a caller typed.
+     */
+    NOT_AN_ABSOLUTE_TEMPLATE = "NOT_AN_ABSOLUTE_TEMPLATE",
+    /**
+     * An ORIGIN placeholder is followed by something other than `/`, `?`, `#` or the end —
+     * `{baseUrl}.evil.test/…`, `{baseUrl}:8443/…`, `{a}{b}/…`. The text after it would extend the host
+     * the origin value names.
+     */
+    ORIGIN_NOT_TERMINATED = "ORIGIN_NOT_TERMINATED",
+    /**
+     * One authority carries more than one placeholder (`https://{a}{b}/…`, `https://{sub}.{domain}/…`).
+     * Each value validated alone can still compose a host no declaration admits.
+     */
+    SEVERAL_PLACEHOLDERS_IN_AUTHORITY = "SEVERAL_PLACEHOLDERS_IN_AUTHORITY",
+    /**
+     * The authority after `://` is empty, begins with `/` or a backslash, or carries a backslash or `@`
+     * before the first `/`, `?` or `#`. The parser skips extra slashes (`https:///{h}/t` dials `{h}` as the
+     * HOST, while the `://` scan sees an empty authority and calls `{h}` a PATH), reads a backslash as a
+     * path separator, and
+     * reads text before `@` as userinfo — each makes the scan and the parser disagree about the host.
+     */
+    MALFORMED_AUTHORITY = "MALFORMED_AUTHORITY"
+}
+/**
+ * A DNS name: one or more LDH labels, lower-case (callers lower-case first).
+ * spec-cite: RFC 1123 §2.1 (a label may begin with a digit) and RFC 1035 §2.3.1 (letters, digits,
+ * hyphen; 63 octets per label).
+ */
+export declare const PROVIDER_OAUTH2_DNS_NAME_PATTERN: RegExp;
+/**
+ * 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
+ * emitted and refused at every connect. Empty when the allowance is sound.
+ *
+ * The runtime resolver refuses each of these too; this exists so they are caught where a human is
+ * already looking at a diff rather than where a person is pressing Connect.
+ */
+export declare function describeProviderOAuth2EndpointHostAllowanceDefects(placeholder: {
+    readonly position: ProviderOAuth2EndpointPlaceholderPosition;
+    readonly occupiesWholeHost: boolean;
+    readonly literalHostSuffix?: string;
+}, allowance: ProviderOAuth2EndpointHostAllowance): readonly string[];
+/**
+ * The defects that make a template unsafe to resolve, or an empty list. Shared by the runtime (which
+ * refuses) and the transposer (which refuses to emit), so neither can admit a shape the other rejects.
+ */
+export declare function findProviderOAuth2EndpointTemplateDefects(template: string): readonly ProviderOAuth2EndpointTemplateDefect[];
+/** The placeholder syntax an endpoint template uses — the same braces the operation path templates use. */
+export declare const PROVIDER_OAUTH2_ENDPOINT_PLACEHOLDER_PATTERN: RegExp;
+/**
+ * Classify every placeholder in an OAuth2 endpoint template by the URL component it forms.
+ *
+ * ONE function, shared by the transposer (which decides which placeholders need an allowance) and
+ * the runtime (which refuses an unallowed one), so the two cannot disagree about what a host is.
+ *
+ * Deliberately a string scan, not a URL parse: a template whose host is still `{cloud}` is not a
+ * parseable URL, which is exactly the population this classifies.
+ *
+ * - offset 0 → {@link ProviderOAuth2EndpointPlaceholderPosition.ORIGIN};
+ * - between the first `://` and the next `/`, `?` or `#` → HOST;
+ * - otherwise → PATH_OR_QUERY.
+ *
+ * This classification is only meaningful for a template with no
+ * {@link findProviderOAuth2EndpointTemplateDefects}: a template that does not begin `http(s)://` or a
+ * placeholder has no authority this scan can find, and every consumer must refuse it FIRST rather than
+ * trust the PATH_OR_QUERY answer it would get here.
+ */
+export declare function classifyProviderOAuth2EndpointPlaceholders(template: string): readonly ProviderOAuth2EndpointPlaceholderOccurrence[];
 /**
  * Vendors whose credential is COMPUTED per request rather than sent as a fixed header.
  *