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

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

@@ -88,6 +88,13 @@ export var ProviderRestResponseDecoding;
     ProviderRestResponseDecoding["TEXT"] = "text";
     /** Read nothing — a write whose answer carries no information (a 204). The output is `undefined`. */
     ProviderRestResponseDecoding["NONE"] = "none";
+    /**
+     * Keep the raw bytes — a signed PDF, an evidence container (#2910). Requires `binaryResponse` (a byte ceiling and the
+     * accepted media types); the output is `{ bytes, contentType }`. The bytes are the vendor's, unscanned: do not relay
+     * them to a person or write them as a file yourself. Keep one through `ProviderDocumentFileWriterBackendService`
+     * (`@wildo-ai/saas-backend-lib`, #2963), which stores it as a scanned file (`scan: REQUIRED`) whatever the caller asks.
+     */
+    ProviderRestResponseDecoding["BINARY"] = "binary";
 })(ProviderRestResponseDecoding || (ProviderRestResponseDecoding = {}));
 /**
  * How a listing operation continues. A HINT the caller reads, never something the executor acts
@@ -102,6 +109,152 @@ export var ProviderRestPaginationStyle;
     /** The vendor returns its own continuation URL (`@odata.nextLink`, `links.next`). */
     ProviderRestPaginationStyle["LINK"] = "link";
 })(ProviderRestPaginationStyle || (ProviderRestPaginationStyle = {}));
+/** What a successful HTTP answer said about the call, read through a {@link ProviderRestApplicationOutcome}. */
+export var ProviderRestApplicationOutcomeKind;
+(function (ProviderRestApplicationOutcomeKind) {
+    /** The success flag is `true`. */
+    ProviderRestApplicationOutcomeKind["SUCCEEDED"] = "succeeded";
+    /** The success flag is `false`: the vendor refused the call, naming why at the error path when it could. */
+    ProviderRestApplicationOutcomeKind["REFUSED"] = "refused";
+    /** The flag is absent or not a boolean: the answer does not carry the envelope its provider declares. */
+    ProviderRestApplicationOutcomeKind["UNSTATED"] = "unstated";
+})(ProviderRestApplicationOutcomeKind || (ProviderRestApplicationOutcomeKind = {}));
+/**
+ * A vendor error code as the engine may carry it: identifier characters only, at most 128. A value of any other shape
+ * is dropped rather than carried, because it travels to audit rows, logs and API answers, and a vendor that puts a
+ * sentence (or request data) where a code belongs must not have it repeated there.
+ */
+export const PROVIDER_VENDOR_ERROR_CODE_SHAPE = /^[A-Za-z0-9_.:-]{1,128}$/;
+/**
+ * The defects of a declared outcome envelope, refused at boot: an empty path, and a credential-refusal code that is not
+ * code-shaped, which the transport would never carry and so would never match (#2661 review L7).
+ */
+export function describeProviderRestApplicationOutcomeDefects(outcome) {
+    const defects = [];
+    const path = /^[A-Za-z0-9_]+(\.[A-Za-z0-9_]+)*$/;
+    if (!path.test(outcome.successFlagPath))
+        defects.push(`applicationOutcome.successFlagPath '${outcome.successFlagPath}' is not a dot-path`);
+    if (!path.test(outcome.errorCodePath))
+        defects.push(`applicationOutcome.errorCodePath '${outcome.errorCodePath}' is not a dot-path`);
+    for (const code of outcome.credentialRefusedErrorCodes ?? []) {
+        if (!PROVIDER_VENDOR_ERROR_CODE_SHAPE.test(code)) {
+            defects.push(`applicationOutcome.credentialRefusedErrorCodes names '${code}', which is not code-shaped and would never match a code the transport keeps`);
+        }
+    }
+    return defects;
+}
+/**
+ * The placeholder a client-credentials token URL may carry for the tenant the credential belongs to:
+ * `https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token`. Filled from the connection's
+ * {@link ProviderRestClientCredentials.tenantSecretRef} slot, never from a request.
+ */
+export const PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER = '{tenant}';
+/** A tenant value the token URL admits: a GUID or a DNS name. Nothing that can leave the URL's path segment. */
+export const PROVIDER_CLIENT_CREDENTIALS_TENANT_SHAPE = /^[A-Za-z0-9](?:[A-Za-z0-9.-]{0,251}[A-Za-z0-9])?$/;
+/** What a {@link ProviderClientCredentialsVerifiedFact} records: a value the person typed and the vendor accepted. */
+export var ProviderClientCredentialsFactSource;
+(function (ProviderClientCredentialsFactSource) {
+    /** The client id the token endpoint issued a token for: Microsoft's bot App ID. */
+    ProviderClientCredentialsFactSource["CLIENT_ID"] = "client_id";
+    /** The tenant whose token endpoint issued it. */
+    ProviderClientCredentialsFactSource["TENANT"] = "tenant";
+})(ProviderClientCredentialsFactSource || (ProviderClientCredentialsFactSource = {}));
+/**
+ * Why a client-credentials declaration cannot be honoured, or an empty list. Checked where a provider is composed:
+ * a token URL that is not https, a token host that is not a DNS name or that the URL is not on, a tenant placeholder
+ * with no tenant slot (or the reverse), or any other placeholder in the URL.
+ */
+export function describeProviderRestClientCredentialsDefects(credentials) {
+    const defects = [];
+    const hasTenant = credentials.tokenUrl.includes(PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER);
+    const filled = credentials.tokenUrl.split(PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER).join('tenant.example');
+    if (/[{}]/.test(filled))
+        defects.push(`clientCredentials.tokenUrl '${credentials.tokenUrl}' carries a placeholder other than ${PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER}`);
+    if (hasTenant && credentials.tenantSecretRef === undefined)
+        defects.push(`clientCredentials.tokenUrl carries ${PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER} and no tenantSecretRef fills it`);
+    if (!hasTenant && credentials.tenantSecretRef !== undefined)
+        defects.push(`clientCredentials.tenantSecretRef '${credentials.tenantSecretRef}' fills nothing: the token URL carries no ${PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER}`);
+    const host = /^https:\/\/([^/:?#]+)(?::\d+)?\//.exec(filled)?.[1]?.toLowerCase();
+    if (host === undefined)
+        defects.push(`clientCredentials.tokenUrl '${credentials.tokenUrl}' is not an https URL with a path`);
+    if (credentials.tokenHosts.length === 0)
+        defects.push('clientCredentials.tokenHosts admits no host');
+    for (const tokenHost of credentials.tokenHosts) {
+        if (!PROVIDER_OAUTH2_DNS_NAME_PATTERN.test(tokenHost.toLowerCase()))
+            defects.push(`clientCredentials.tokenHosts names '${tokenHost}', which is not a DNS name`);
+    }
+    if (host !== undefined && !credentials.tokenHosts.some((tokenHost) => tokenHost.toLowerCase() === host)) {
+        defects.push(`clientCredentials.tokenUrl is on '${host}', which tokenHosts does not admit`);
+    }
+    if (credentials.scope.trim() === '')
+        defects.push('clientCredentials.scope is empty');
+    for (const [name, fact] of Object.entries(credentials.verifiedAccountFacts ?? {})) {
+        if (!/^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(name))
+            defects.push(`clientCredentials.verifiedAccountFacts names '${name}', which is not a fact name`);
+        if (fact.source === ProviderClientCredentialsFactSource.TENANT && credentials.tenantSecretRef === undefined) {
+            defects.push(`clientCredentials.verifiedAccountFacts '${name}' records the tenant, and no tenantSecretRef holds one`);
+        }
+    }
+    if (credentials.tokenLifetimeFallbackSeconds !== undefined && !(credentials.tokenLifetimeFallbackSeconds > 0)) {
+        defects.push('clientCredentials.tokenLifetimeFallbackSeconds is not a positive number');
+    }
+    return defects;
+}
+function readDotPath(body, path) {
+    let current = body;
+    for (const segment of path.split('.')) {
+        if (current === null || typeof current !== 'object' || !Object.hasOwn(current, segment))
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+/**
+ * The vendor's error code at `errorCodePath` in a parsed answer, when it is code-shaped. Used for a refused 2xx and for
+ * a non-2xx answer alike: a vendor that states its code in the body states it in the same place whatever the status.
+ */
+export function readProviderVendorErrorCode(body, errorCodePath) {
+    const code = readDotPath(body, errorCodePath);
+    return typeof code === 'string' && PROVIDER_VENDOR_ERROR_CODE_SHAPE.test(code) ? code : undefined;
+}
+/** Reads the verdict a parsed JSON answer carries. The ONE reader: the transport and every test go through it. */
+export function readProviderRestApplicationOutcome(body, outcome) {
+    const flag = readDotPath(body, outcome.successFlagPath);
+    if (flag === true)
+        return { kind: ProviderRestApplicationOutcomeKind.SUCCEEDED };
+    if (flag !== false)
+        return { kind: ProviderRestApplicationOutcomeKind.UNSTATED };
+    const errorCode = readProviderVendorErrorCode(body, outcome.errorCodePath);
+    return errorCode === undefined
+        ? { kind: ProviderRestApplicationOutcomeKind.REFUSED }
+        : { kind: ProviderRestApplicationOutcomeKind.REFUSED, errorCode };
+}
+/**
+ * The QUERY parameters an operation declares under a name its provider places a credential in, compared IGNORING CASE
+ * (#2123, #2707). Empty when there is none.
+ *
+ * Such a parameter asks the caller for the credential the contract already places, so the operation would send the key
+ * twice, or send the caller's value instead of the configured one. A name differing only in case travels BESIDE the
+ * credential, and a vendor that reads names without regard to case may read the caller's value. Both are a declaration
+ * defect.
+ *
+ * ONE comparison for every place that refuses it, so they cannot drift apart:
+ * - the operation executor, once per catalogue load, against the contract's `apiKey.queryParameterName`;
+ * - the operation request builder, on every call, against the resolved access's query-placed names (the backstop for a
+ *   placement that does not come from the contract);
+ * - `wildo` registry module checks, at publish, against the module's own contract.
+ *
+ * A PATH or HEADER parameter is not compared: a path token is a resource id that may merely be spelled like a
+ * credential, and a header credential is refused by its own placement rules.
+ */
+export function providerRestOperationCredentialQueryParameters(operation, credentialQueryParameterNames) {
+    const credentialNames = new Set([...credentialQueryParameterNames].map((name) => name.toLowerCase()));
+    if (credentialNames.size === 0)
+        return [];
+    return (operation.parameters ?? [])
+        .filter((parameter) => parameter.in === ProviderRestParameterLocation.QUERY && credentialNames.has(parameter.name.toLowerCase()))
+        .map((parameter) => parameter.name);
+}
 /** @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).
@@ -179,6 +332,24 @@ export function selectProviderRateBudgetDeclarations(input) {
 /** @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}';
+/** What a vendor's URI scopes name, which decides the audience a scope belongs to — see {@link ProviderRestOAuth2.scopeMeaning}. */
+export var ProviderOAuth2ScopeMeaning;
+(function (ProviderOAuth2ScopeMeaning) {
+    /**
+     * A URI scope names the RESOURCE a token is minted for: the scope without its last path segment
+     * (`https://graph.microsoft.com/Mail.Send` is Graph's). Microsoft's model, and the default.
+     */
+    ProviderOAuth2ScopeMeaning["RESOURCE"] = "RESOURCE";
+    /**
+     * A URI scope names a PERMISSION of the vendor's one grant, not a resource: Google's scopes are URIs on several hosts
+     * (`https://www.googleapis.com/auth/gmail.readonly`, `https://mail.google.com/`, `https://spreadsheets.google.com/feeds`)
+     * and every one is consented on the same grant, whose one token serves every Google API. So every scope belongs to the
+     * PRIMARY audience, whatever host its URI names. Declared with a single audience only.
+     * spec-cite: https://developers.google.com/identity/protocols/oauth2/scopes — the scope tables, which list both forms
+     * (fetched 2026-10-05).
+     */
+    ProviderOAuth2ScopeMeaning["PERMISSION"] = "PERMISSION";
+})(ProviderOAuth2ScopeMeaning || (ProviderOAuth2ScopeMeaning = {}));
 /** 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();
@@ -202,6 +373,10 @@ export function selectProviderOAuth2AudienceForHost(oauth2, host) {
     }
     return undefined;
 }
+/** Whether `audience` mints its token per request ORIGIN (a mint scope beginning {@link PROVIDER_OAUTH2_AUDIENCE_ORIGIN_PLACEHOLDER}). */
+export function providerOAuth2AudienceIsOriginScoped(audience) {
+    return audience.mintScopes.some((scope) => scope.startsWith(PROVIDER_OAUTH2_AUDIENCE_ORIGIN_PLACEHOLDER));
+}
 /**
  * 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
@@ -229,6 +404,9 @@ export function findProviderOAuth2ScopeAudience(oauth2, scope) {
     const audiences = oauth2.audiences ?? {};
     if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(scope))
         return oauth2.primaryAudience;
+    // A vendor whose scopes name permissions of one grant (Google): every scope is the primary audience's (#2546).
+    if (oauth2.scopeMeaning === ProviderOAuth2ScopeMeaning.PERMISSION)
+        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.
@@ -262,6 +440,39 @@ export function providerOAuth2ScopeNamesDeclaredAudience(oauth2, scope) {
         return true;
     return findProviderOAuth2ScopeAudience(oauth2, scope) !== undefined;
 }
+/**
+ * Why an operation's {@link ProviderRestOperation.host} cannot be used on a provider whose REST binding is `contract`, or
+ * `undefined` when it can (#2546). The token a call carries is chosen by the base URL's host, so the operation's host
+ * must belong to that same audience: then the same token is valid there and nothing is minted for it.
+ */
+export function describeProviderRestOperationHostDefect(host, contract) {
+    if (host !== host.toLowerCase() || !PROVIDER_OAUTH2_DNS_NAME_PATTERN.test(host)) {
+        return `host '${host}' is not a lower-case DNS name (no scheme, port, path or placeholder)`;
+    }
+    if (contract.oauth2?.audiences === undefined) {
+        return `host '${host}' is declared on a provider whose connection declares no OAuth2 audiences, so its credential is valid only on the base URL's own host`;
+    }
+    // The base URL's https host, read without a URL parser (this package carries no DOM or Node types): the authority up to
+    // the first '/', '?' or '#'. Anything that is not a plain DNS name there (a placeholder, userinfo, a port) has no fixed
+    // audience and is refused.
+    const authority = contract.baseUrl === undefined ? undefined : /^https:\/\/([^/?#]*)/i.exec(contract.baseUrl)?.[1]?.toLowerCase();
+    const baseHost = authority !== undefined && PROVIDER_OAUTH2_DNS_NAME_PATTERN.test(authority) ? authority : undefined;
+    if (baseHost === undefined)
+        return `host '${host}' is declared on a provider whose base URL is not one fixed https URL, so the audience its token belongs to is not known`;
+    const baseAudience = selectProviderOAuth2AudienceForHost(contract.oauth2, baseHost);
+    const hostAudience = selectProviderOAuth2AudienceForHost(contract.oauth2, host);
+    if (hostAudience === undefined)
+        return `host '${host}' is admitted by none of the connection's audiences (${Object.keys(contract.oauth2.audiences).join(', ')})`;
+    if (baseAudience?.id !== hostAudience.id) {
+        return `host '${host}' belongs to the audience '${hostAudience.id}', not to '${baseAudience?.id ?? '(none)'}' that the base URL's token is for; an operation on another audience is a provider of its own sharing the connection`;
+    }
+    // An audience whose token is minted per ORIGIN (`{audienceOrigin}/.default`, a Dataverse environment) gives the base
+    // URL's origin its own token, which is not valid on another origin the same audience admits.
+    if (host !== baseHost && providerOAuth2AudienceIsOriginScoped(hostAudience.audience)) {
+        return `host '${host}' is another origin of the audience '${hostAudience.id}', whose token is minted for one origin at a time (the base URL's)`;
+    }
+    return 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 */
 /**
@@ -286,6 +497,69 @@ export var ProviderOAuth2IncrementalConsentForm;
      */
     ProviderOAuth2IncrementalConsentForm["INCLUDE_GRANTED_SCOPES"] = "INCLUDE_GRANTED_SCOPES";
 })(ProviderOAuth2IncrementalConsentForm || (ProviderOAuth2IncrementalConsentForm = {}));
+/**
+ * How a vendor is asked for a refresh token, when a scope does not do it — see {@link ProviderRestOAuth2.offlineAccess}.
+ */
+export var ProviderOAuth2OfflineAccessForm;
+(function (ProviderOAuth2OfflineAccessForm) {
+    /**
+     * Google: the authorize request carries `access_type=offline`, without which no refresh token is issued. The parameter
+     * "Indicates whether your application can refresh access tokens when the user is not present at the browser. Valid
+     * parameter values are `online`, which is the default value, and `offline`."; and "the refresh token is only returned
+     * if your application set the `access_type` parameter to `offline`".
+     * spec-cite: https://developers.google.com/identity/protocols/oauth2/web-server — Step 1 (`access_type` row) and
+     * Step 5, fetched 2026-10-05.
+     *
+     * Google issues the refresh token at the FIRST exchange for a consent, so a request that does not grow an existing grant
+     * (a first connect, or a reconnect replacing a grant) also carries `prompt=consent`: a reconnect of an account that had
+     * already consented would otherwise store a grant with no refresh token, which expires within the hour. A request that
+     * grows a grant (`include_granted_scopes`) does not need it, because the stored grant keeps its refresh token.
+     * Decided by practice: the established Google integrations ask for `access_type=offline` with `prompt=consent` for
+     * exactly this reason.
+     */
+    ProviderOAuth2OfflineAccessForm["ACCESS_TYPE_OFFLINE"] = "ACCESS_TYPE_OFFLINE";
+})(ProviderOAuth2OfflineAccessForm || (ProviderOAuth2OfflineAccessForm = {}));
+/** Whether a vendor takes PKCE from a confidential client. See {@link ProviderRestOAuth2.pkce}. */
+export var ProviderOAuth2PkceSupport;
+(function (ProviderOAuth2PkceSupport) {
+    /** An S256 challenge on the authorize request and its verifier on the exchange: the default. */
+    ProviderOAuth2PkceSupport["S256"] = "S256";
+    /** The vendor refuses PKCE from a confidential client (Slack): neither is sent. */
+    ProviderOAuth2PkceSupport["NOT_ACCEPTED"] = "NOT_ACCEPTED";
+})(ProviderOAuth2PkceSupport || (ProviderOAuth2PkceSupport = {}));
+/**
+ * A `scope` list encoding that deviates from RFC 6749's space-delimited list, in either direction: the token answer
+ * ({@link ProviderRestOAuth2.grantedScopesDelimiter}) or the authorize request ({@link ProviderRestOAuth2.authorizeScopesDelimiter}).
+ * One vocabulary for both, because it is one question (how a vendor writes a list of scopes) asked of two messages.
+ */
+export var ProviderOAuth2ScopeListDelimiter;
+(function (ProviderOAuth2ScopeListDelimiter) {
+    /**
+     * GitHub's token answer is `{"access_token":"gho_…","scope":"repo,gist","token_type":"bearer"}`, while its authorize
+     * request takes "A space-delimited list of scopes". Slack's authorize URL takes "a comma-separated list of scopes, such
+     * as: `scope=incoming-webhook,commands`".
+     * spec-cite: https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps — step 2's JSON
+     * response example and step 1's `scope` row, fetched 2026-10-05; https://docs.slack.dev/authentication/installing-with-oauth
+     * — the authorize step's `scope` parameter, fetched 2026-10-06.
+     */
+    ProviderOAuth2ScopeListDelimiter["COMMA"] = "COMMA";
+})(ProviderOAuth2ScopeListDelimiter || (ProviderOAuth2ScopeListDelimiter = {}));
+/**
+ * The granted scopes a token answer's `scope` string names, read with the vendor's declared delimiter: whitespace (RFC
+ * 6749 §5.1) when none is declared, a comma for {@link ProviderOAuth2ScopeListDelimiter.COMMA}.
+ */
+export function splitProviderOAuth2GrantedScopes(scope, delimiter) {
+    const separator = delimiter === ProviderOAuth2ScopeListDelimiter.COMMA ? /\s*,\s*/ : /\s+/;
+    return scope.split(separator).map((token) => token.trim()).filter((token) => token.length > 0);
+}
+/**
+ * The authorize request's `scope` value for the scopes asked for, written with the vendor's declared delimiter: a single
+ * space (RFC 6749 §3.3) when none is declared, a comma for {@link ProviderOAuth2ScopeListDelimiter.COMMA}.
+ * spec-cite: RFC 6749 §3.3 (scope is expressed as a list of space-delimited, case-sensitive strings).
+ */
+export function joinProviderOAuth2RequestedScopes(scopes, delimiter) {
+    return scopes.join(delimiter === ProviderOAuth2ScopeListDelimiter.COMMA ? ',' : ' ');
+}
 /** @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
@@ -302,6 +576,10 @@ export function describeProviderOAuth2AudienceDefects(oauth2) {
     if (audiences === undefined) {
         return oauth2.primaryAudience === undefined ? [] : [`primaryAudience '${oauth2.primaryAudience}' is declared with no audiences`];
     }
+    // Under PERMISSION every scope is the primary audience's, so a second audience could never be asked for (#2546).
+    if (oauth2.scopeMeaning === ProviderOAuth2ScopeMeaning.PERMISSION && Object.keys(audiences).length > 1) {
+        return [`scopeMeaning PERMISSION reads every scope as the primary audience's, so it is declared with one audience; this declares ${Object.keys(audiences).length}`];
+    }
     const defects = [];
     const primary = oauth2.primaryAudience === undefined ? undefined : audiences[oauth2.primaryAudience];
     if (primary === undefined)
@@ -347,6 +625,134 @@ export function describeProviderOAuth2AudienceDefects(oauth2) {
     }
     return defects;
 }
+/** Where in the token endpoint's answer a {@link ProviderOAuth2ReportedAccountFact} is read. */
+export var ProviderOAuth2ReportedFactSource;
+(function (ProviderOAuth2ReportedFactSource) {
+    /** The token endpoint's JSON answer itself: Slack's `team.id`, Salesforce's `instance_url`. The default. */
+    ProviderOAuth2ReportedFactSource["TOKEN_RESPONSE"] = "token_response";
+    /**
+     * The claims of the `id_token` that answer carries (OpenID Connect): Microsoft's `tid`, the tenant the person signed
+     * in to. Read without checking the token's signature, which the specification permits for an ID token received
+     * directly from the token endpoint, because TLS has already authenticated who sent it. An answer carrying no
+     * `id_token` reports no such fact. This is how a vendor's account identity becomes VENDOR-REPORTED when its token
+     * answer names the account only inside the ID token (#2660).
+     * spec-cite: OpenID Connect Core 1.0 §3.1.3.7, item 6.
+     */
+    ProviderOAuth2ReportedFactSource["ID_TOKEN_CLAIMS"] = "id_token_claims";
+})(ProviderOAuth2ReportedFactSource || (ProviderOAuth2ReportedFactSource = {}));
+/** What a {@link ProviderOAuth2IdTokenRequirement} asks of the sign-in's ID token claims. */
+export var ProviderOAuth2IdTokenRequirementKind;
+(function (ProviderOAuth2IdTokenRequirementKind) {
+    /**
+     * The claim is an array holding at least one of `values`, compared exactly. Microsoft's `wids`, the directory roles
+     * the person holds: a tenant claim requires a role that administers the tenant.
+     */
+    ProviderOAuth2IdTokenRequirementKind["CLAIM_CONTAINS_ANY"] = "claim_contains_any";
+    /**
+     * When the claim is present, it equals `equalsClaim`. Microsoft's `idp` against `iss`: they differ for a guest, an
+     * account another tenant authenticated, who speaks for nothing in this one.
+     */
+    ProviderOAuth2IdTokenRequirementKind["CLAIM_EQUALS_CLAIM_WHEN_PRESENT"] = "claim_equals_claim_when_present";
+})(ProviderOAuth2IdTokenRequirementKind || (ProviderOAuth2IdTokenRequirementKind = {}));
+/** Why an ID token's claims may not be used (#2663 re-review I1). See {@link providerOAuth2IdTokenRejection}. */
+export var ProviderOAuth2IdTokenRejection;
+(function (ProviderOAuth2IdTokenRejection) {
+    /** The token endpoint's answer carries no ID token, or not one whose payload is a JSON object. */
+    ProviderOAuth2IdTokenRejection["ABSENT"] = "absent";
+    /** `iss` is not the declared issuer, with its placeholders filled from the token's claims. */
+    ProviderOAuth2IdTokenRejection["ISSUER_MISMATCH"] = "issuer_mismatch";
+    /** `aud` does not name this client, or names another audience beside it. */
+    ProviderOAuth2IdTokenRejection["AUDIENCE_MISMATCH"] = "audience_mismatch";
+    /** `exp` is missing, or not after the current time. */
+    ProviderOAuth2IdTokenRejection["EXPIRED"] = "expired";
+})(ProviderOAuth2IdTokenRejection || (ProviderOAuth2IdTokenRejection = {}));
+/**
+ * Why these ID token claims may not be used, or `undefined` when they may: the token names the declared issuer, this
+ * client as its only audience, and an expiry still ahead. See {@link ProviderRestOAuth2.idTokenIssuer}.
+ *
+ * A placeholder of the issuer naming a claim the token does not carry as a non-empty string fails the issuer check:
+ * an issuer that cannot be written cannot be matched.
+ */
+export function providerOAuth2IdTokenRejection(claims, expected) {
+    if (claims === undefined)
+        return ProviderOAuth2IdTokenRejection.ABSENT;
+    const claimOf = (name) => (Object.hasOwn(claims, name) ? claims[name] : undefined);
+    let unfillable = false;
+    const issuer = expected.issuer.replace(/\{([^{}]+)\}/g, (_placeholder, name) => {
+        const value = claimOf(name);
+        if (typeof value !== 'string' || value.length === 0) {
+            unfillable = true;
+            return '';
+        }
+        return value;
+    });
+    if (unfillable || claimOf('iss') !== issuer)
+        return ProviderOAuth2IdTokenRejection.ISSUER_MISMATCH;
+    const audience = claimOf('aud');
+    const audiences = Array.isArray(audience) ? audience : [audience];
+    // Every listed audience must be this client: OpenID Connect rejects a token that lists "additional audiences not
+    // trusted by the Client", and this client trusts none but itself (no declaration names another).
+    if (audiences.length === 0 || !audiences.every((entry) => entry === expected.clientId))
+        return ProviderOAuth2IdTokenRejection.AUDIENCE_MISMATCH;
+    const expiry = claimOf('exp');
+    if (typeof expiry !== 'number' || !Number.isFinite(expiry) || expiry <= expected.nowEpochSeconds)
+        return ProviderOAuth2IdTokenRejection.EXPIRED;
+    return undefined;
+}
+/** Whether ID token claims meet one requirement. An absent ID token meets none. */
+export function providerOAuth2IdTokenRequirementHolds(requirement, claims) {
+    if (claims === undefined)
+        return false;
+    const value = Object.hasOwn(claims, requirement.claim) ? claims[requirement.claim] : undefined;
+    switch (requirement.kind) {
+        case ProviderOAuth2IdTokenRequirementKind.CLAIM_CONTAINS_ANY:
+            return Array.isArray(value) && value.some((entry) => typeof entry === 'string' && requirement.values.includes(entry));
+        case ProviderOAuth2IdTokenRequirementKind.CLAIM_EQUALS_CLAIM_WHEN_PRESENT: {
+            if (value === undefined)
+                return true;
+            const other = Object.hasOwn(claims, requirement.equalsClaim) ? claims[requirement.equalsClaim] : undefined;
+            return typeof value === 'string' && value === other;
+        }
+        default: {
+            const unhandled = requirement;
+            return unhandled;
+        }
+    }
+}
+/**
+ * What makes a declaration of ID token requirements unusable: a requirement with no claim or no value, and any
+ * requirement on a contract that does not ask for `openid`, without which "the behavior is entirely unspecified" and
+ * no ID token is returned to read.
+ * spec-cite: OpenID Connect Core 1.0 §3.1.2.1 — the `scope` parameter row ("If the openid scope value is not present,
+ * the behavior is entirely unspecified").
+ */
+export function describeProviderOAuth2IdTokenRequirementDefects(oauth2) {
+    const requirements = oauth2.idTokenRequirements ?? [];
+    const readsIdTokenFacts = Object.values(oauth2.reportedAccountFacts ?? {}).some((fact) => fact.source === ProviderOAuth2ReportedFactSource.ID_TOKEN_CLAIMS);
+    if (requirements.length === 0 && !readsIdTokenFacts)
+        return [];
+    const defects = [];
+    if (!(oauth2.scopes ?? []).includes('openid'))
+        defects.push('reads ID token claims without asking for the `openid` scope, so no ID token is returned to read them from');
+    // OpenID Connect Core §3.1.3.7 item 2: a claim is used only from a token naming the expected issuer.
+    if (oauth2.idTokenIssuer === undefined || oauth2.idTokenIssuer.trim().length === 0) {
+        defects.push('reads ID token claims without declaring `idTokenIssuer`, the issuer a token must name before any of its claims is used');
+    }
+    else if (!oauth2.idTokenIssuer.startsWith('https://')) {
+        defects.push(`declares \`idTokenIssuer\` ${JSON.stringify(oauth2.idTokenIssuer)}, which is not an https URL as an OpenID issuer identifier is`);
+    }
+    for (const [index, requirement] of requirements.entries()) {
+        if (requirement.claim.trim().length === 0)
+            defects.push(`ID token requirement ${index} names no claim`);
+        if (requirement.kind === ProviderOAuth2IdTokenRequirementKind.CLAIM_CONTAINS_ANY && requirement.values.length === 0) {
+            defects.push(`ID token requirement ${index} (${requirement.claim}) admits no value, so no sign-in could meet it`);
+        }
+        if (requirement.kind === ProviderOAuth2IdTokenRequirementKind.CLAIM_EQUALS_CLAIM_WHEN_PRESENT && requirement.equalsClaim.trim().length === 0) {
+            defects.push(`ID token requirement ${index} (${requirement.claim}) names no claim to equal`);
+        }
+    }
+    return defects;
+}
 /** How a placeholder's value is compared with a declared one. */
 export var ProviderOAuth2ValueComparison;
 (function (ProviderOAuth2ValueComparison) {