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

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

@@ -19,7 +19,31 @@
  * 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.
  */
+/** @wildo_source:part:start external-connectors.models.rest-operation-contract facet:layer:shared facet:family:provider facet:audience:app-developer */
 /** Where a declared parameter rides on the wire. */
 export var ProviderRestParameterLocation;
 (function (ProviderRestParameterLocation) {
@@ -40,7 +64,31 @@ export var ProviderRestRequestBodyEncoding;
     ProviderRestRequestBodyEncoding["MULTIPART"] = "multipart";
     /** A raw text body; `contentType` on the declaration says which media type is sent. */
     ProviderRestRequestBodyEncoding["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.
+     */
+    ProviderRestRequestBodyEncoding["BINARY"] = "binary";
 })(ProviderRestRequestBodyEncoding || (ProviderRestRequestBodyEncoding = {}));
+/**
+ * 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 var ProviderRestResponseDecoding;
+(function (ProviderRestResponseDecoding) {
+    /** Parse the body as JSON. The default, and what an absent `responseDecoding` means. */
+    ProviderRestResponseDecoding["JSON"] = "json";
+    /** Keep the body as text — a CSV export, an XML document. The operation's output is that string. */
+    ProviderRestResponseDecoding["TEXT"] = "text";
+    /** Read nothing — a write whose answer carries no information (a 204). The output is `undefined`. */
+    ProviderRestResponseDecoding["NONE"] = "none";
+})(ProviderRestResponseDecoding || (ProviderRestResponseDecoding = {}));
 /**
  * How a listing operation continues. A HINT the caller reads, never something the executor acts
  * on: an executor that paged on its own would decide a caller's memory budget for it, and the
@@ -54,6 +102,661 @@ export var ProviderRestPaginationStyle;
     /** The vendor returns its own continuation URL (`@odata.nextLink`, `links.next`). */
     ProviderRestPaginationStyle["LINK"] = "link";
 })(ProviderRestPaginationStyle || (ProviderRestPaginationStyle = {}));
+/** @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 var ProviderRateBudgetPartition;
+(function (ProviderRateBudgetPartition) {
+    /** One allowance for the whole connection — every ref, every account it acts for, every process. */
+    ProviderRateBudgetPartition["CONNECTION"] = "connection";
+    /** One allowance per account the connection acts for — the grant's owner (a person, an organization, the deployment). */
+    ProviderRateBudgetPartition["OWNER"] = "owner";
+})(ProviderRateBudgetPartition || (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 var RateBudgetCounting;
+(function (RateBudgetCounting) {
+    RateBudgetCounting["SHARED"] = "shared";
+    RateBudgetCounting["PROCESS"] = "process";
+})(RateBudgetCounting || (RateBudgetCounting = {}));
+/**
+ * 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 function describeProviderRateBudgetDefects(input) {
+    const defects = [];
+    const check = (where, declarations) => {
+        for (const [index, declaration] of (declarations ?? []).entries()) {
+            if (!Number.isInteger(declaration.maxRequests) || declaration.maxRequests < 1) {
+                defects.push(`${where}[${index}].maxRequests must be a positive integer (got ${String(declaration.maxRequests)})`);
+            }
+            if (!Number.isFinite(declaration.windowSeconds) || declaration.windowSeconds <= 0) {
+                defects.push(`${where}[${index}].windowSeconds must be positive (got ${String(declaration.windowSeconds)})`);
+            }
+            if (!Object.values(ProviderRateBudgetPartition).includes(declaration.partition)) {
+                defects.push(`${where}[${index}].partition '${String(declaration.partition)}' is not a ProviderRateBudgetPartition`);
+            }
+        }
+    };
+    check('rest.rateBudgets', input.contractRateBudgets);
+    for (const [id, audience] of Object.entries(input.audiences ?? {}))
+        check(`oauth2.audiences.${id}.rateBudgets`, audience.rateBudgets);
+    if ((input.contractRateBudgets?.length ?? 0) > 0 && Object.keys(input.audiences ?? {}).length > 0) {
+        defects.push('rest.rateBudgets is declared beside oauth2.audiences and would apply to no call — declare each limit on the audience it meters');
+    }
+    return defects;
+}
+/**
+ * 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 function selectProviderRateBudgetDeclarations(input) {
+    return input.audience !== undefined ? input.audience.rateBudgets ?? [] : input.contractRateBudgets ?? [];
+}
+/** @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 const PROVIDER_OAUTH2_AUDIENCE_ORIGIN_PLACEHOLDER = '{audienceOrigin}';
+/** Whether `host` is admitted by one audience's hosts: an exact value, or `<labels><suffix>` for a declared suffix. */
+export function providerOAuth2AudienceAdmitsHost(audience, host) {
+    const candidate = host.toLowerCase();
+    if (audience.hosts.values.some((value) => value.toLowerCase() === candidate))
+        return true;
+    return (audience.hosts.hostSuffixes ?? []).some((suffix) => {
+        const lowered = suffix.toLowerCase();
+        if (!candidate.endsWith(lowered) || candidate.length === lowered.length)
+            return false;
+        return PROVIDER_OAUTH2_DNS_NAME_PATTERN.test(candidate.slice(0, candidate.length - lowered.length));
+    });
+}
+/**
+ * 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 function selectProviderOAuth2AudienceForHost(oauth2, host) {
+    for (const [id, audience] of Object.entries(oauth2.audiences ?? {})) {
+        if (providerOAuth2AudienceAdmitsHost(audience, host))
+            return { id, audience, primary: id === oauth2.primaryAudience };
+    }
+    return 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 function resolveProviderOAuth2AudienceMintScopes(audience, origin) {
+    return audience.mintScopes.map((scope) => (scope.startsWith(PROVIDER_OAUTH2_AUDIENCE_ORIGIN_PLACEHOLDER)
+        ? `${origin}${scope.slice(PROVIDER_OAUTH2_AUDIENCE_ORIGIN_PLACEHOLDER.length)}`
+        : scope));
+}
+/**
+ * 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 function findProviderOAuth2ScopeAudience(oauth2, scope) {
+    const audiences = oauth2.audiences ?? {};
+    if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(scope))
+        return oauth2.primaryAudience;
+    // The https origin's host, read by the same shape the audiences declare (a DNS name, no port, no credentials) rather
+    // than by a URL parser: this package runs in a browser-neutral program with no URL global, and a scope that is not
+    // that shape names no host an audience could admit.
+    const origin = /^https:\/\/([^/?#:@]+)(?:\/|$)/i.exec(scope);
+    const host = origin?.[1]?.toLowerCase();
+    for (const [id, audience] of Object.entries(audiences)) {
+        for (const mintScope of audience.mintScopes) {
+            if (mintScope.startsWith(PROVIDER_OAUTH2_AUDIENCE_ORIGIN_PLACEHOLDER)) {
+                if (host !== undefined && PROVIDER_OAUTH2_DNS_NAME_PATTERN.test(host) && providerOAuth2AudienceAdmitsHost(audience, host))
+                    return id;
+                continue;
+            }
+            const resource = mintScope.slice(0, mintScope.lastIndexOf('/'));
+            if (resource.length > 0 && scope.startsWith(`${resource}/`))
+                return id;
+        }
+    }
+    return 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 function providerOAuth2ScopeNamesDeclaredAudience(oauth2, scope) {
+    if (oauth2.audiences === undefined)
+        return true;
+    if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(scope))
+        return true;
+    return findProviderOAuth2ScopeAudience(oauth2, scope) !== undefined;
+}
+/** @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 var ProviderOAuth2IncrementalConsentForm;
+(function (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.
+     */
+    ProviderOAuth2IncrementalConsentForm["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.
+     */
+    ProviderOAuth2IncrementalConsentForm["INCLUDE_GRANTED_SCOPES"] = "INCLUDE_GRANTED_SCOPES";
+})(ProviderOAuth2IncrementalConsentForm || (ProviderOAuth2IncrementalConsentForm = {}));
+/** @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 function describeProviderOAuth2AudienceDefects(oauth2) {
+    const audiences = oauth2.audiences;
+    if (audiences === undefined) {
+        return oauth2.primaryAudience === undefined ? [] : [`primaryAudience '${oauth2.primaryAudience}' is declared with no audiences`];
+    }
+    const defects = [];
+    const primary = oauth2.primaryAudience === undefined ? undefined : audiences[oauth2.primaryAudience];
+    if (primary === undefined)
+        defects.push(`primaryAudience '${String(oauth2.primaryAudience)}' names no declared audience`);
+    for (const [id, audience] of Object.entries(audiences)) {
+        if (audience.hosts.values.length === 0 && (audience.hosts.hostSuffixes ?? []).length === 0)
+            defects.push(`audience '${id}' admits no host`);
+        for (const suffix of audience.hosts.hostSuffixes ?? []) {
+            if (!suffix.startsWith('.') || !PROVIDER_OAUTH2_DNS_NAME_PATTERN.test(suffix.slice(1).toLowerCase()))
+                defects.push(`audience '${id}' declares the host suffix '${suffix}', which is not '.<dns-name>'`);
+        }
+        for (const value of audience.hosts.values) {
+            if (!PROVIDER_OAUTH2_DNS_NAME_PATTERN.test(value.toLowerCase()))
+                defects.push(`audience '${id}' declares the host '${value}', which is not a DNS name`);
+        }
+        if (audience.mintScopes.length === 0)
+            defects.push(`audience '${id}' declares no mint scope`);
+        for (const scope of audience.mintScopes) {
+            const rest = scope.startsWith(PROVIDER_OAUTH2_AUDIENCE_ORIGIN_PLACEHOLDER) ? scope.slice(PROVIDER_OAUTH2_AUDIENCE_ORIGIN_PLACEHOLDER.length) : scope;
+            if (rest.includes('{') || rest.includes('}'))
+                defects.push(`audience '${id}' mint scope '${scope}' carries a placeholder other than a leading ${PROVIDER_OAUTH2_AUDIENCE_ORIGIN_PLACEHOLDER}`);
+        }
+    }
+    if (primary !== undefined) {
+        for (const scope of primary.mintScopes) {
+            if (scope.startsWith(PROVIDER_OAUTH2_AUDIENCE_ORIGIN_PLACEHOLDER))
+                defects.push(`the primary audience '${oauth2.primaryAudience}' mint scope '${scope}' names a per-request origin; the authorization must be for one fixed resource`);
+            else if (!(oauth2.scopes ?? []).includes(scope))
+                defects.push(`the primary audience '${oauth2.primaryAudience}' mint scope '${scope}' is not among the authorization's own scopes`);
+        }
+    }
+    const entries = Object.entries(audiences);
+    for (let left = 0; left < entries.length; left += 1) {
+        for (let right = left + 1; right < entries.length; right += 1) {
+            const [leftId, leftAudience] = entries[left];
+            const [rightId, rightAudience] = entries[right];
+            const overlap = leftAudience.hosts.values.some((host) => providerOAuth2AudienceAdmitsHost(rightAudience, host))
+                || rightAudience.hosts.values.some((host) => providerOAuth2AudienceAdmitsHost(leftAudience, host))
+                || (leftAudience.hosts.hostSuffixes ?? []).some((suffix) => (rightAudience.hosts.hostSuffixes ?? []).some((other) => suffix.toLowerCase().endsWith(other.toLowerCase()) || other.toLowerCase().endsWith(suffix.toLowerCase())));
+            if (overlap)
+                defects.push(`audiences '${leftId}' and '${rightId}' admit a common host; a request host must select one token`);
+        }
+    }
+    return defects;
+}
+/** How a placeholder's value is compared with a declared one. */
+export var ProviderOAuth2ValueComparison;
+(function (ProviderOAuth2ValueComparison) {
+    /** A host or an origin: DNS names compare case-insensitively. spec-cite: RFC 4343 §2. */
+    ProviderOAuth2ValueComparison["CASE_INSENSITIVE"] = "CASE_INSENSITIVE";
+    /** A scope value: scope strings are case-sensitive. spec-cite: RFC 6749 §3.3. */
+    ProviderOAuth2ValueComparison["EXACT"] = "EXACT";
+})(ProviderOAuth2ValueComparison || (ProviderOAuth2ValueComparison = {}));
+/**
+ * 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 function findProviderOAuth2UnsupportedValueReason(unsupportedValues, value, comparison) {
+    if (unsupportedValues === undefined)
+        return undefined;
+    const key = comparison === ProviderOAuth2ValueComparison.EXACT
+        ? (Object.hasOwn(unsupportedValues, value) ? value : undefined)
+        : Object.keys(unsupportedValues).find((candidate) => candidate.toLowerCase() === value.toLowerCase());
+    return key === undefined ? undefined : unsupportedValues[key];
+}
+/**
+ * Why a declared unsupported-value map contradicts the admitted set it sits beside, or an empty list: a value both
+ * admitted and declined would make the refusal reason a lie, and a declined value with no reason says nothing.
+ */
+function describeProviderOAuth2UnsupportedValueDefects(unsupportedValues, admitted, comparison) {
+    if (unsupportedValues === undefined)
+        return [];
+    const defects = [];
+    const normalise = (value) => (comparison === ProviderOAuth2ValueComparison.EXACT ? value : value.toLowerCase());
+    const admittedSet = new Set(admitted.map(normalise));
+    for (const [value, reason] of Object.entries(unsupportedValues)) {
+        if (admittedSet.has(normalise(value)))
+            defects.push(`'${value}' is both admitted and declared unsupported`);
+        if (typeof reason !== 'string' || reason.trim() === '')
+            defects.push(`unsupported value '${value}' states no reason`);
+    }
+    return defects;
+}
+/**
+ * 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 var ProviderOAuth2ScopePlaceholderPosition;
+(function (ProviderOAuth2ScopePlaceholderPosition) {
+    /**
+     * The placeholder begins the scope and is followed by `/` — `{hostUrl}/.default`. Its value is an
+     * https ORIGIN, admitted only within {@link ProviderRestOAuth2.endpointHostAllowances}.
+     */
+    ProviderOAuth2ScopePlaceholderPosition["ORIGIN"] = "ORIGIN";
+    /**
+     * The placeholder is the entire scope entry — `{permissions}`. Its value is one of
+     * {@link ProviderRestOAuth2.scopeValueAllowances}.
+     */
+    ProviderOAuth2ScopePlaceholderPosition["WHOLE_SCOPE"] = "WHOLE_SCOPE";
+})(ProviderOAuth2ScopePlaceholderPosition || (ProviderOAuth2ScopePlaceholderPosition = {}));
+/** Why a scope entry cannot be resolved safely, whatever is supplied. See {@link findProviderOAuth2ScopeTemplateDefects}. */
+export var ProviderOAuth2ScopeTemplateDefect;
+(function (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.
+     */
+    ProviderOAuth2ScopeTemplateDefect["UNSUPPORTED_PLACEHOLDER_POSITION"] = "UNSUPPORTED_PLACEHOLDER_POSITION";
+    /** More than one placeholder in one scope entry: each value validated alone can compose an undeclared one. */
+    ProviderOAuth2ScopeTemplateDefect["SEVERAL_PLACEHOLDERS"] = "SEVERAL_PLACEHOLDERS";
+    /** A `{` or `}` that is not part of a well-formed placeholder: a vendor can never grant a scope carrying one. */
+    ProviderOAuth2ScopeTemplateDefect["STRAY_BRACE"] = "STRAY_BRACE";
+})(ProviderOAuth2ScopeTemplateDefect || (ProviderOAuth2ScopeTemplateDefect = {}));
+/**
+ * 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 function findProviderOAuth2ScopeTemplateDefects(scope) {
+    const occurrences = [...scope.matchAll(PROVIDER_OAUTH2_ENDPOINT_PLACEHOLDER_PATTERN)];
+    const withoutPlaceholders = scope.replace(PROVIDER_OAUTH2_ENDPOINT_PLACEHOLDER_PATTERN, '');
+    const defects = [];
+    if (withoutPlaceholders.includes('{') || withoutPlaceholders.includes('}'))
+        defects.push(ProviderOAuth2ScopeTemplateDefect.STRAY_BRACE);
+    if (occurrences.length > 1)
+        defects.push(ProviderOAuth2ScopeTemplateDefect.SEVERAL_PLACEHOLDERS);
+    const first = occurrences[0];
+    if (first !== undefined) {
+        const next = scope.charAt((first.index ?? 0) + first[0].length);
+        if ((first.index ?? 0) !== 0 || (next !== '' && next !== '/'))
+            defects.push(ProviderOAuth2ScopeTemplateDefect.UNSUPPORTED_PLACEHOLDER_POSITION);
+    }
+    return defects;
+}
+/**
+ * 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 function classifyProviderOAuth2ScopePlaceholder(scope) {
+    const match = /^\{([A-Za-z_][A-Za-z0-9_]*)\}/.exec(scope);
+    if (match === null)
+        return undefined;
+    return {
+        name: match[1],
+        position: match[0].length === scope.length ? ProviderOAuth2ScopePlaceholderPosition.WHOLE_SCOPE : ProviderOAuth2ScopePlaceholderPosition.ORIGIN,
+        token: match[0],
+    };
+}
+/**
+ * One scope token: printable ASCII except space, `"` and backslash.
+ * spec-cite: RFC 6749 §3.3 (scope-token = 1*( %x21 / %x23-5B / %x5D-7E )).
+ * Braces are additionally refused: a value carrying one would read as a placeholder nobody resolves.
+ */
+const PROVIDER_OAUTH2_SCOPE_TOKEN_PATTERN = /^[\x21\x23-\x5B\x5D-\x7A\x7C\x7E]+$/;
+/**
+ * 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 function describeProviderOAuth2ScopeValueAllowanceDefects(allowance) {
+    const defects = [];
+    if (!Array.isArray(allowance.values) || allowance.values.length === 0)
+        return ['a scope value allowance admits nothing'];
+    for (const value of allowance.values) {
+        const tokens = typeof value === 'string' ? value.split(' ') : [];
+        if (typeof value !== 'string' || value.length === 0 || !tokens.every((token) => PROVIDER_OAUTH2_SCOPE_TOKEN_PATTERN.test(token))) {
+            defects.push(`'${String(value)}' is not a space-delimited list of scope tokens`);
+        }
+    }
+    defects.push(...describeProviderOAuth2UnsupportedValueDefects(allowance.unsupportedValues, allowance.values, ProviderOAuth2ValueComparison.EXACT));
+    return defects;
+}
+/**
+ * Where a `{placeholder}` sits inside an OAuth2 endpoint template — the classification the host
+ * allow-list keys on. See {@link classifyProviderOAuth2EndpointPlaceholders}.
+ */
+export var ProviderOAuth2EndpointPlaceholderPosition;
+(function (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.
+     */
+    ProviderOAuth2EndpointPlaceholderPosition["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.
+     */
+    ProviderOAuth2EndpointPlaceholderPosition["HOST"] = "HOST";
+    /** Anywhere after the authority. Percent-encoded, so it cannot move the request to another host. */
+    ProviderOAuth2EndpointPlaceholderPosition["PATH_OR_QUERY"] = "PATH_OR_QUERY";
+})(ProviderOAuth2EndpointPlaceholderPosition || (ProviderOAuth2EndpointPlaceholderPosition = {}));
+/** How a host- or origin-forming placeholder may be filled. See {@link ProviderRestOAuth2.endpointHostAllowances}. */
+export var ProviderOAuth2EndpointHostAllowanceKind;
+(function (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.
+     */
+    ProviderOAuth2EndpointHostAllowanceKind["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.
+     */
+    ProviderOAuth2EndpointHostAllowanceKind["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.
+     */
+    ProviderOAuth2EndpointHostAllowanceKind["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."
+     */
+    ProviderOAuth2EndpointHostAllowanceKind["DERIVED_FROM_CONNECTION_ANSWER"] = "DERIVED_FROM_CONNECTION_ANSWER";
+})(ProviderOAuth2EndpointHostAllowanceKind || (ProviderOAuth2EndpointHostAllowanceKind = {}));
+/**
+ * Why an OAuth2 endpoint TEMPLATE cannot be resolved safely, whatever values are supplied.
+ * See {@link findProviderOAuth2EndpointTemplateDefects}.
+ */
+export var ProviderOAuth2EndpointTemplateDefect;
+(function (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.
+     */
+    ProviderOAuth2EndpointTemplateDefect["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.
+     */
+    ProviderOAuth2EndpointTemplateDefect["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.
+     */
+    ProviderOAuth2EndpointTemplateDefect["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.
+     */
+    ProviderOAuth2EndpointTemplateDefect["MALFORMED_AUTHORITY"] = "MALFORMED_AUTHORITY";
+})(ProviderOAuth2EndpointTemplateDefect || (ProviderOAuth2EndpointTemplateDefect = {}));
+/**
+ * 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 const PROVIDER_OAUTH2_DNS_NAME_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$/;
+/**
+ * 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 function describeProviderOAuth2EndpointHostAllowanceDefects(placeholder, allowance) {
+    const defects = [];
+    if (placeholder.position === ProviderOAuth2EndpointPlaceholderPosition.PATH_OR_QUERY) {
+        return ['a PATH or QUERY placeholder takes no host allowance'];
+    }
+    if (allowance.kind === ProviderOAuth2EndpointHostAllowanceKind.DEPLOYMENT_BASE_URL) {
+        if (placeholder.position !== ProviderOAuth2EndpointPlaceholderPosition.ORIGIN) {
+            defects.push('DEPLOYMENT_BASE_URL fills an ORIGIN only, and this placeholder does not begin its endpoint');
+        }
+        if (allowance.baseUrlPathSuffix !== undefined && !/^\/[^?#]*[^/?#]$/.test(allowance.baseUrlPathSuffix)) {
+            defects.push(`baseUrlPathSuffix '${allowance.baseUrlPathSuffix}' must begin with '/' and name a path (no trailing '/', query or fragment)`);
+        }
+        return defects;
+    }
+    if (allowance.kind === ProviderOAuth2EndpointHostAllowanceKind.DERIVED_FROM_CONNECTION_ANSWER) {
+        if (placeholder.position !== ProviderOAuth2EndpointPlaceholderPosition.HOST || !placeholder.occupiesWholeHost) {
+            defects.push('DERIVED_FROM_CONNECTION_ANSWER fills a WHOLE HOST only, and this placeholder is not one');
+        }
+        if (typeof allowance.answer !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(allowance.answer)) {
+            defects.push(`answer '${String(allowance.answer)}' is not a placeholder name`);
+        }
+        const hosts = Object.values(allowance.hosts ?? {});
+        if (hosts.length === 0)
+            defects.push('DERIVED_FROM_CONNECTION_ANSWER maps no answer to a host, which admits nothing');
+        for (const host of [...hosts, ...(allowance.whenUnanswered === undefined ? [] : [allowance.whenUnanswered])]) {
+            if (typeof host !== 'string' || !PROVIDER_OAUTH2_DNS_NAME_PATTERN.test(host.toLowerCase()))
+                defects.push(`'${String(host)}' is not a DNS name`);
+        }
+        defects.push(...describeProviderOAuth2UnsupportedValueDefects(allowance.unsupportedValues, Object.keys(allowance.hosts ?? {}), ProviderOAuth2ValueComparison.CASE_INSENSITIVE));
+        return defects;
+    }
+    if (allowance.kind === ProviderOAuth2EndpointHostAllowanceKind.DEPLOYMENT_CONFIGURED) {
+        if (placeholder.position !== ProviderOAuth2EndpointPlaceholderPosition.HOST || !placeholder.occupiesWholeHost) {
+            defects.push('DEPLOYMENT_CONFIGURED fills a WHOLE HOST only, and this placeholder is not one');
+        }
+        if (typeof allowance.envVarName !== 'string' || !/^[A-Z][A-Z0-9_]*$/.test(allowance.envVarName)) {
+            defects.push(`envVarName '${String(allowance.envVarName)}' is not an upper-case environment variable name`);
+        }
+        return defects;
+    }
+    if (allowance.originMatchesDeploymentBaseUrl === true && placeholder.position !== ProviderOAuth2EndpointPlaceholderPosition.ORIGIN) {
+        defects.push('originMatchesDeploymentBaseUrl applies to an ORIGIN only, and this placeholder is not one');
+    }
+    if (allowance.values.length === 0 && (allowance.hostSuffixes ?? []).length === 0) {
+        defects.push('DECLARED_VALUES admits nothing');
+    }
+    for (const value of allowance.values) {
+        if (placeholder.position === ProviderOAuth2EndpointPlaceholderPosition.ORIGIN) {
+            // Matched as text, not with `URL`: this package compiles without a DOM or Node lib. A lower-case
+            // `https://` + DNS name, with nothing after the host but an optional port, is exactly an origin as
+            // `URL#origin` would print it back.
+            const match = /^https:\/\/([^:/?#@]+)(?::\d{1,5})?$/.exec(value);
+            if (match === null || !PROVIDER_OAUTH2_DNS_NAME_PATTERN.test(match[1])) {
+                defects.push(`'${value}' is not an https origin (scheme and lower-case host only)`);
+            }
+        }
+        else if (!PROVIDER_OAUTH2_DNS_NAME_PATTERN.test(value.toLowerCase())) {
+            defects.push(`'${value}' is not a DNS name`);
+        }
+    }
+    for (const suffix of allowance.hostSuffixes ?? []) {
+        // An ORIGIN is a whole authority by construction (the scheme is then fixed to https); a HOST
+        // placeholder qualifies only when nothing surrounds it inside the authority.
+        // A placeholder that OPENS the host qualifies too, but only for the ONE suffix the template itself writes after
+        // it (#1015): any other suffix would be concatenated with that literal into a host nobody declared.
+        const opensHostWithThisSuffix = placeholder.literalHostSuffix !== undefined && placeholder.literalHostSuffix.toLowerCase() === suffix.toLowerCase();
+        if (placeholder.position === ProviderOAuth2EndpointPlaceholderPosition.HOST && !placeholder.occupiesWholeHost && !opensHostWithThisSuffix) {
+            defects.push(`host suffix '${suffix}' on a placeholder that is not the whole host`);
+            continue;
+        }
+        const labels = suffix.startsWith('.') ? suffix.slice(1) : '';
+        if (!PROVIDER_OAUTH2_DNS_NAME_PATTERN.test(labels.toLowerCase()) || !labels.includes('.')) {
+            defects.push(`host suffix '${suffix}' must begin with '.' and name at least two DNS labels (a bare '.com' admits every host under a TLD)`);
+        }
+    }
+    defects.push(...describeProviderOAuth2UnsupportedValueDefects(allowance.unsupportedValues, allowance.values, ProviderOAuth2ValueComparison.CASE_INSENSITIVE));
+    for (const declined of Object.keys(allowance.unsupportedValues ?? {})) {
+        // A declined value a declared SUFFIX would still admit is admitted, whatever the reason says.
+        const coveringSuffix = (allowance.hostSuffixes ?? []).find((suffix) => declined.toLowerCase().endsWith(suffix.toLowerCase()));
+        if (coveringSuffix !== undefined)
+            defects.push(`'${declined}' is declared unsupported but the host suffix '${coveringSuffix}' admits it`);
+    }
+    return defects;
+}
+/**
+ * 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 function findProviderOAuth2EndpointTemplateDefects(template) {
+    const defects = [];
+    const leadingPlaceholder = /^\{[A-Za-z_][A-Za-z0-9_]*\}/.exec(template);
+    if (!/^https?:\/\//i.test(template) && leadingPlaceholder === null) {
+        return [ProviderOAuth2EndpointTemplateDefect.NOT_AN_ABSOLUTE_TEMPLATE];
+    }
+    if (leadingPlaceholder !== null) {
+        const next = template.charAt(leadingPlaceholder[0].length);
+        if (next !== '' && next !== '/' && next !== '?' && next !== '#')
+            defects.push(ProviderOAuth2EndpointTemplateDefect.ORIGIN_NOT_TERMINATED);
+    }
+    else {
+        const afterScheme = template.slice(template.indexOf('://') + 3);
+        const authorityEnd = afterScheme.search(/[/?#]/);
+        const authority = authorityEnd < 0 ? afterScheme : afterScheme.slice(0, authorityEnd);
+        if (authority === '' || authority.includes('\\') || authority.includes('@')) {
+            defects.push(ProviderOAuth2EndpointTemplateDefect.MALFORMED_AUTHORITY);
+            return defects;
+        }
+        const hostPlaceholders = classifyProviderOAuth2EndpointPlaceholders(template)
+            .filter((occurrence) => occurrence.position === ProviderOAuth2EndpointPlaceholderPosition.HOST);
+        if (hostPlaceholders.length > 1)
+            defects.push(ProviderOAuth2EndpointTemplateDefect.SEVERAL_PLACEHOLDERS_IN_AUTHORITY);
+    }
+    return defects;
+}
+/** The placeholder syntax an endpoint template uses — the same braces the operation path templates use. */
+export const PROVIDER_OAUTH2_ENDPOINT_PLACEHOLDER_PATTERN = /\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+/**
+ * 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 function classifyProviderOAuth2EndpointPlaceholders(template) {
+    const schemeSeparator = template.indexOf('://');
+    let authorityEnd = -1;
+    if (schemeSeparator >= 0) {
+        const rest = template.slice(schemeSeparator + 3);
+        const end = rest.search(/[/?#]/);
+        authorityEnd = end < 0 ? template.length : schemeSeparator + 3 + end;
+    }
+    const occurrences = [];
+    for (const match of template.matchAll(PROVIDER_OAUTH2_ENDPOINT_PLACEHOLDER_PATTERN)) {
+        const index = match.index ?? 0;
+        const position = index === 0
+            ? ProviderOAuth2EndpointPlaceholderPosition.ORIGIN
+            : schemeSeparator >= 0 && index > schemeSeparator && index < authorityEnd
+                ? ProviderOAuth2EndpointPlaceholderPosition.HOST
+                : ProviderOAuth2EndpointPlaceholderPosition.PATH_OR_QUERY;
+        const occupiesWholeHost = position === ProviderOAuth2EndpointPlaceholderPosition.HOST
+            && index === schemeSeparator + 3
+            && index + match[0].length === authorityEnd;
+        const followingLiteral = position === ProviderOAuth2EndpointPlaceholderPosition.HOST && !occupiesWholeHost && index === schemeSeparator + 3
+            ? template.slice(index + match[0].length, authorityEnd)
+            : undefined;
+        // Only a PURELY literal remainder qualifies: a second placeholder in the authority is refused as malformed anyway.
+        const literalHostSuffix = followingLiteral !== undefined && followingLiteral.startsWith('.') && !followingLiteral.includes('{') ? followingLiteral : undefined;
+        occurrences.push({ name: match[1], position, index, token: match[0], occupiesWholeHost, ...(literalHostSuffix === undefined ? {} : { literalHostSuffix }) });
+    }
+    return occurrences;
+}
 /**
  * Vendors whose credential is COMPUTED per request rather than sent as a fixed header.
  *