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

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;
@@ -173,6 +296,7 @@ export interface ProviderRestOperationCatalogue {
     /** Keyed by `operationId`. */
     readonly operations: Readonly<Record<string, ProviderRestOperation>>;
 }
+/** @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).
  *
@@ -239,9 +363,57 @@ 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.us/.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[];
     /**
@@ -252,12 +424,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 +447,351 @@ 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.us/.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>>;
+}
+/** 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[];
 }
+/**
+ * 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 two login clouds,
+     * 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"
+}
+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;
+} | {
+    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.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.
  *