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

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

@@ -102,6 +102,289 @@ 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}.
  *
@@ -191,6 +474,7 @@ export function describeProviderOAuth2ScopeValueAllowanceDefects(allowance) {
             defects.push(`'${String(value)}' is not a space-delimited list of scope tokens`);
         }
     }
+    defects.push(...describeProviderOAuth2UnsupportedValueDefects(allowance.unsupportedValues, allowance.values, ProviderOAuth2ValueComparison.EXACT));
     return defects;
 }
 /**
@@ -218,7 +502,7 @@ export var ProviderOAuth2EndpointPlaceholderPosition;
 export var ProviderOAuth2EndpointHostAllowanceKind;
 (function (ProviderOAuth2EndpointHostAllowanceKind) {
     /**
-     * Chosen at connect time from values the provider DECLARES — Microsoft's two login clouds,
+     * 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).
      *
@@ -248,6 +532,21 @@ export var ProviderOAuth2EndpointHostAllowanceKind;
      * 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.
@@ -310,6 +609,23 @@ export function describeProviderOAuth2EndpointHostAllowanceDefects(placeholder,
         }
         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');
@@ -354,6 +670,13 @@ export function describeProviderOAuth2EndpointHostAllowanceDefects(placeholder,
             defects.push(`host suffix '${suffix}' must begin with '.' and name at least two DNS labels (a bare '.com' admits every host under a TLD)`);
         }
     }
+    defects.push(...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;
 }
 /**