@wildo-ai/external-connectors-models 1.1.10 → 1.1.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (110) hide show
  1. package/dist/esm/companion-exports.js.map +1 -1
  2. package/dist/esm/core/commons.external-connectors-models.schemas.d.ts +140 -0
  3. package/dist/esm/core/commons.external-connectors-models.schemas.d.ts.map +1 -1
  4. package/dist/esm/core/commons.external-connectors-models.schemas.js +203 -0
  5. package/dist/esm/core/commons.external-connectors-models.schemas.js.map +1 -1
  6. package/dist/esm/core/oauth2.enums.d.ts.map +1 -1
  7. package/dist/esm/core/oauth2.enums.js.map +1 -1
  8. package/dist/esm/core/operation-classification.external-connectors-models.schemas.d.ts.map +1 -1
  9. package/dist/esm/core/operation-classification.external-connectors-models.schemas.js.map +1 -1
  10. package/dist/esm/core/operations.external-connectors-models.schemas.js.map +1 -1
  11. package/dist/esm/core/security.external-connectors-models.schemas.d.ts +4 -2
  12. package/dist/esm/core/security.external-connectors-models.schemas.d.ts.map +1 -1
  13. package/dist/esm/core/security.external-connectors-models.schemas.js +10 -4
  14. package/dist/esm/core/security.external-connectors-models.schemas.js.map +1 -1
  15. package/dist/esm/index.d.ts +8 -0
  16. package/dist/esm/index.d.ts.map +1 -1
  17. package/dist/esm/index.js +8 -0
  18. package/dist/esm/index.js.map +1 -1
  19. package/dist/esm/protocols/agent-client-protocol.external-connectors-models.schemas.d.ts +9 -42
  20. package/dist/esm/protocols/agent-client-protocol.external-connectors-models.schemas.d.ts.map +1 -1
  21. package/dist/esm/protocols/agent-client-protocol.external-connectors-models.schemas.js +31 -1
  22. package/dist/esm/protocols/agent-client-protocol.external-connectors-models.schemas.js.map +1 -1
  23. package/dist/esm/protocols/billing.standard-interface.schemas.d.ts +64 -3
  24. package/dist/esm/protocols/billing.standard-interface.schemas.d.ts.map +1 -1
  25. package/dist/esm/protocols/billing.standard-interface.schemas.js +23 -2
  26. package/dist/esm/protocols/billing.standard-interface.schemas.js.map +1 -1
  27. package/dist/esm/protocols/content-safety.external-connectors-models.schemas.d.ts +150 -0
  28. package/dist/esm/protocols/content-safety.external-connectors-models.schemas.d.ts.map +1 -0
  29. package/dist/esm/protocols/content-safety.external-connectors-models.schemas.js +182 -0
  30. package/dist/esm/protocols/content-safety.external-connectors-models.schemas.js.map +1 -0
  31. package/dist/esm/protocols/document-extraction.external-connectors-models.schemas.d.ts +41 -9
  32. package/dist/esm/protocols/document-extraction.external-connectors-models.schemas.d.ts.map +1 -1
  33. package/dist/esm/protocols/document-extraction.external-connectors-models.schemas.js +40 -14
  34. package/dist/esm/protocols/document-extraction.external-connectors-models.schemas.js.map +1 -1
  35. package/dist/esm/protocols/electronic-signature.external-connectors-models.schemas.d.ts +157 -0
  36. package/dist/esm/protocols/electronic-signature.external-connectors-models.schemas.d.ts.map +1 -0
  37. package/dist/esm/protocols/electronic-signature.external-connectors-models.schemas.js +134 -0
  38. package/dist/esm/protocols/electronic-signature.external-connectors-models.schemas.js.map +1 -0
  39. package/dist/esm/protocols/email-inbound.standard-interface.schemas.d.ts +85 -0
  40. package/dist/esm/protocols/email-inbound.standard-interface.schemas.d.ts.map +1 -1
  41. package/dist/esm/protocols/email-inbound.standard-interface.schemas.js +46 -2
  42. package/dist/esm/protocols/email-inbound.standard-interface.schemas.js.map +1 -1
  43. package/dist/esm/protocols/email.external-connectors-models.schemas.js.map +1 -1
  44. package/dist/esm/protocols/email.standard-interface.schemas.d.ts.map +1 -1
  45. package/dist/esm/protocols/email.standard-interface.schemas.js +4 -0
  46. package/dist/esm/protocols/email.standard-interface.schemas.js.map +1 -1
  47. package/dist/esm/protocols/embeddings.external-connectors-models.schemas.d.ts +86 -10
  48. package/dist/esm/protocols/embeddings.external-connectors-models.schemas.d.ts.map +1 -1
  49. package/dist/esm/protocols/embeddings.external-connectors-models.schemas.js +146 -7
  50. package/dist/esm/protocols/embeddings.external-connectors-models.schemas.js.map +1 -1
  51. package/dist/esm/protocols/file-storage.standard-interface.d.ts +14 -1
  52. package/dist/esm/protocols/file-storage.standard-interface.d.ts.map +1 -1
  53. package/dist/esm/protocols/file-storage.standard-interface.js +6 -0
  54. package/dist/esm/protocols/file-storage.standard-interface.js.map +1 -1
  55. package/dist/esm/protocols/frontend.external-connectors-models.schemas.js.map +1 -1
  56. package/dist/esm/protocols/graphql-operations.external-connectors-models.schemas.d.ts +254 -0
  57. package/dist/esm/protocols/graphql-operations.external-connectors-models.schemas.d.ts.map +1 -0
  58. package/dist/esm/protocols/graphql-operations.external-connectors-models.schemas.js +480 -0
  59. package/dist/esm/protocols/graphql-operations.external-connectors-models.schemas.js.map +1 -0
  60. package/dist/esm/protocols/hooks-capability.external-connectors-models.schemas.d.ts +7 -2
  61. package/dist/esm/protocols/hooks-capability.external-connectors-models.schemas.d.ts.map +1 -1
  62. package/dist/esm/protocols/hooks-capability.external-connectors-models.schemas.js.map +1 -1
  63. package/dist/esm/protocols/hooks.external-connectors-models.schemas.d.ts +482 -7
  64. package/dist/esm/protocols/hooks.external-connectors-models.schemas.d.ts.map +1 -1
  65. package/dist/esm/protocols/hooks.external-connectors-models.schemas.js +348 -0
  66. package/dist/esm/protocols/hooks.external-connectors-models.schemas.js.map +1 -1
  67. package/dist/esm/protocols/image.external-connectors-models.schemas.js.map +1 -1
  68. package/dist/esm/protocols/llm.external-connectors-models.schemas.d.ts +165 -8
  69. package/dist/esm/protocols/llm.external-connectors-models.schemas.d.ts.map +1 -1
  70. package/dist/esm/protocols/llm.external-connectors-models.schemas.js +243 -20
  71. package/dist/esm/protocols/llm.external-connectors-models.schemas.js.map +1 -1
  72. package/dist/esm/protocols/oauth2-provider-assurance.definitions.js.map +1 -1
  73. package/dist/esm/protocols/oauth2-provider-assurance.schemas.js.map +1 -1
  74. package/dist/esm/protocols/oauth2.external-connectors-models.schemas.js.map +1 -1
  75. package/dist/esm/protocols/provider-configuration-authoring.external-connectors-models.schemas.d.ts +52 -0
  76. package/dist/esm/protocols/provider-configuration-authoring.external-connectors-models.schemas.d.ts.map +1 -0
  77. package/dist/esm/protocols/provider-configuration-authoring.external-connectors-models.schemas.js +132 -0
  78. package/dist/esm/protocols/provider-configuration-authoring.external-connectors-models.schemas.js.map +1 -0
  79. package/dist/esm/protocols/provider-connection-parameters.external-connectors-models.d.ts +111 -0
  80. package/dist/esm/protocols/provider-connection-parameters.external-connectors-models.d.ts.map +1 -0
  81. package/dist/esm/protocols/provider-connection-parameters.external-connectors-models.js +203 -0
  82. package/dist/esm/protocols/provider-connection-parameters.external-connectors-models.js.map +1 -0
  83. package/dist/esm/protocols/provider-oauth2-token-endpoint-hosts.external-connectors-models.d.ts +6 -0
  84. package/dist/esm/protocols/provider-oauth2-token-endpoint-hosts.external-connectors-models.d.ts.map +1 -1
  85. package/dist/esm/protocols/provider-oauth2-token-endpoint-hosts.external-connectors-models.js +13 -7
  86. package/dist/esm/protocols/provider-oauth2-token-endpoint-hosts.external-connectors-models.js.map +1 -1
  87. package/dist/esm/protocols/provider-vendor-registration.external-connectors-models.d.ts +50 -0
  88. package/dist/esm/protocols/provider-vendor-registration.external-connectors-models.d.ts.map +1 -0
  89. package/dist/esm/protocols/provider-vendor-registration.external-connectors-models.js +30 -0
  90. package/dist/esm/protocols/provider-vendor-registration.external-connectors-models.js.map +1 -0
  91. package/dist/esm/protocols/rest-operations.external-connectors-models.schemas.d.ts +1165 -11
  92. package/dist/esm/protocols/rest-operations.external-connectors-models.schemas.d.ts.map +1 -1
  93. package/dist/esm/protocols/rest-operations.external-connectors-models.schemas.js +1217 -9
  94. package/dist/esm/protocols/rest-operations.external-connectors-models.schemas.js.map +1 -1
  95. package/dist/esm/protocols/service-account-token.external-connectors-models.schemas.d.ts +73 -0
  96. package/dist/esm/protocols/service-account-token.external-connectors-models.schemas.d.ts.map +1 -0
  97. package/dist/esm/protocols/service-account-token.external-connectors-models.schemas.js +82 -0
  98. package/dist/esm/protocols/service-account-token.external-connectors-models.schemas.js.map +1 -0
  99. package/dist/esm/protocols/sms.external-connectors-models.schemas.js.map +1 -1
  100. package/dist/esm/protocols/sms.standard-interface.schemas.d.ts +79 -1
  101. package/dist/esm/protocols/sms.standard-interface.schemas.d.ts.map +1 -1
  102. package/dist/esm/protocols/sms.standard-interface.schemas.js +93 -0
  103. package/dist/esm/protocols/sms.standard-interface.schemas.js.map +1 -1
  104. package/dist/esm/protocols/subject-erasure-effect.standard-interface.d.ts +133 -0
  105. package/dist/esm/protocols/subject-erasure-effect.standard-interface.d.ts.map +1 -0
  106. package/dist/esm/protocols/subject-erasure-effect.standard-interface.js +61 -0
  107. package/dist/esm/protocols/subject-erasure-effect.standard-interface.js.map +1 -0
  108. package/dist/tsconfig.build.tsbuildinfo +1 -1
  109. package/package.json +5 -5
  110. package/dist/esm/.native.tsbuildinfo +0 -1
@@ -46,7 +46,8 @@
46
46
  import { z } from 'zod';
47
47
  import { API_HttpMethod } from '../core/commons.external-connectors-models.schemas';
48
48
  import { ExternalOperation_Classification } from '../core/operation-classification.external-connectors-models.schemas';
49
- import type { ExternalProvider_ConnectionTarget } from '../core/security.external-connectors-models.schemas';
49
+ import { ExternalProvider_Connection_OwnerScope, type ExternalProvider_ConnectionTarget } from '../core/security.external-connectors-models.schemas';
50
+ import type { ProviderRestOperationGraphql } from './graphql-operations.external-connectors-models.schemas';
50
51
  /** @wildo_source:part:start external-connectors.models.rest-operation-contract facet:layer:shared facet:family:provider facet:audience:app-developer */
51
52
  /** Where a declared parameter rides on the wire. */
52
53
  export declare enum ProviderRestParameterLocation {
@@ -88,7 +89,21 @@ export declare enum ProviderRestResponseDecoding {
88
89
  /** Keep the body as text — a CSV export, an XML document. The operation's output is that string. */
89
90
  TEXT = "text",
90
91
  /** Read nothing — a write whose answer carries no information (a 204). The output is `undefined`. */
91
- NONE = "none"
92
+ NONE = "none",
93
+ /**
94
+ * Keep the raw bytes — a signed PDF, an evidence container (#2910). Requires `binaryResponse` (a byte ceiling and the
95
+ * accepted media types); the output is `{ bytes, contentType }`. The bytes are the vendor's, unscanned: do not relay
96
+ * them to a person or write them as a file yourself. Keep one through `ProviderDocumentFileWriterBackendService`
97
+ * (`@wildo-ai/saas-backend-lib`, #2963), which stores it as a scanned file (`scan: REQUIRED`) whatever the caller asks.
98
+ */
99
+ BINARY = "binary"
100
+ }
101
+ /** The bounds a {@link ProviderRestResponseDecoding.BINARY} answer is read under (#2910). Both mandatory. */
102
+ export interface ProviderRestBinaryResponse {
103
+ /** The most bytes the vendor's answer may hold. Enforced while streaming; a larger answer is refused, never truncated. */
104
+ readonly maxBytes: number;
105
+ /** Media types accepted (`application/pdf`), compared on the type alone, case-insensitively. */
106
+ readonly acceptedContentTypes: readonly string[];
92
107
  }
93
108
  /**
94
109
  * How a listing operation continues. A HINT the caller reads, never something the executor acts
@@ -118,6 +133,27 @@ export interface ProviderRestOperationParameter {
118
133
  readonly required?: boolean;
119
134
  /** A literal value sent on every call — for a version pin or a fixed format selector. */
120
135
  readonly constantValue?: string;
136
+ /**
137
+ * PATH only (#2663): the value may hold several `/`-separated segments, each percent-encoded on its own, instead of
138
+ * one segment whose `/` is encoded. For a vendor that routes per region or tenant inside ONE origin: the Bot
139
+ * Connector's `serviceUrl` is `https://smba.trafficmanager.net/<region>/…`, and an operation's path begins with that
140
+ * region path. Empty segments, `.` and `..` are refused, so the value moves the path within the base origin and never
141
+ * above it; the origin itself cannot move, as for every path value.
142
+ */
143
+ readonly multiSegment?: true;
144
+ /**
145
+ * PATH only (#3397): the value is the CONNECTION's vendor-reported fact of this name, never the caller's input. Every
146
+ * QuickBooks path is `/v3/company/{realmId}/…`, and the company is the one the person connected, so asking each caller
147
+ * for it would let a call name a company its connection was not made for and leave every application re-typing it.
148
+ *
149
+ * The fact must be declared on the connection's OAuth2 contract with a
150
+ * {@link ProviderOAuth2ReportedAccountFact.pathSegmentPattern}; the access resolver re-admits the stored value on every
151
+ * call and hands it to the request compiler, which fills nothing else from it. A caller value under the same input
152
+ * name is refused rather than ignored, and the operation's `inputSchema` must not declare one
153
+ * ({@link describeProviderRestOperationConnectionFactDefects}). Exclusive with `from`, `constantValue` and
154
+ * `multiSegment`.
155
+ */
156
+ readonly connectionFact?: string;
121
157
  readonly description?: string;
122
158
  }
123
159
  /** How the request body is built from the operation's input. */
@@ -186,12 +222,50 @@ export interface ProviderRestOperationInputOptions {
186
222
  /** Dot-path, inside each listed item, to the text a person reads (`name`). Vendor content, never derived from the value. */
187
223
  readonly labelPath: string;
188
224
  /**
189
- * Inputs the options depend on: `{ <options-operation input field>: <this operation's input field> }`.
225
+ * Inputs the options depend on: `{ <options-operation input field>: <this operation's input field PATH> }`.
226
+ * The value side is a dot path into this operation's input, like the `inputOptions` key (#3399): Jira's issue
227
+ * types depend on `project.key`. The key side is a top-level field of the options operation's own input.
190
228
  * A choice that is not yet made is REFUSED by name rather than listed as empty — "no projects" and
191
229
  * "choose a workspace first" are different answers, and only one of them is true.
192
230
  */
193
231
  readonly dependsOn?: Readonly<Record<string, string>>;
232
+ /**
233
+ * Fixed values the options operation is called with, beside what `dependsOn` forwards (#3399): Jira lists only the
234
+ * projects a person may create in (`action: 'create'`), Box lists the root folder (`folder_id: '0'`). A field may
235
+ * not be both fixed and forwarded.
236
+ */
237
+ readonly input?: Readonly<Record<string, string | number | boolean>>;
238
+ /**
239
+ * Dot path, inside the options operation's output, to the listed items, when that output is an object rather than the
240
+ * list itself (#3399): QuickBooks answers a query as `{ Customer: [...] }`, Box a folder as `{ entries: [...] }`. An
241
+ * object without that path lists nothing, which is how QuickBooks answers a query with no rows; anything else at the
242
+ * path that is not a list is an unreadable answer. Absent, the output itself must be the list.
243
+ */
244
+ readonly itemsPath?: string;
245
+ /**
246
+ * Keeps only the listed items whose value at each dot path equals the given text (#3399): a folder's items are files,
247
+ * folders and web links, and only a folder can be a parent (`{ type: 'folder' }`). Absent, every item is a choice.
248
+ */
249
+ readonly itemWhere?: Readonly<Record<string, string>>;
194
250
  }
251
+ /**
252
+ * Why an operation's `inputOptions` cannot be honoured, or an empty list (#3399). Each key, and each `dependsOn` value,
253
+ * is a dot path into the operation's input (`project.key`, `CustomerRef.value`; a top-level field is a one-segment
254
+ * path), and must name a field the operation's `inputSchema` declares. Checked where a catalogue loads (the operation
255
+ * executor, an augmentation or supplement merge) and at publish, so a mistyped path is refused once, by name, instead of
256
+ * offering a picker that fills nothing. An operation without an `inputSchema` passes its input through unvalidated and
257
+ * declares no fields, so there is nothing to check its paths against; only their shape is.
258
+ */
259
+ export declare function describeProviderRestOperationInputOptionsDefects(operation: Pick<ProviderRestOperation, 'operationId' | 'inputSchema' | 'inputOptions'>): string[];
260
+ /**
261
+ * Why an operation's {@link ProviderRestOperationParameter.connectionFact} parameters cannot be honoured, or an empty
262
+ * list (#3397). Each must be a PATH parameter the path template uses, fed by nothing else (no `from`, `constantValue` or
263
+ * `multiSegment`), and the operation's `inputSchema` must not declare a field of its name: a caller is never asked for a
264
+ * value the connection supplies, and one it sends anyway is refused at the call. With `reportedAccountFacts` (the
265
+ * connection's OAuth2 declaration), each named fact must also be declared there with a `pathSegmentPattern`; without
266
+ * it the request compiler refuses the call, so a module walk passes them to catch it before any call.
267
+ */
268
+ export declare function describeProviderRestOperationConnectionFactDefects(operation: Pick<ProviderRestOperation, 'operationId' | 'pathTemplate' | 'parameters' | 'inputSchema'>, reportedAccountFacts?: Readonly<Record<string, ProviderOAuth2ReportedAccountFact>>): string[];
195
269
  /**
196
270
  * A provider operation, hand-authored. The unit an application addresses:
197
271
  * `executeProviderOperation({ providerRef: 'slack', operationId: 'conversations.list', input })`.
@@ -207,6 +281,19 @@ export interface ProviderRestOperation {
207
281
  readonly method: API_HttpMethod;
208
282
  /** Relative to the provider's base URL. `{token}` interpolates a PATH parameter of that name. */
209
283
  readonly pathTemplate: string;
284
+ /**
285
+ * The API host this operation is served on, when it is not the base URL's host (#2546): an exact lower-case DNS name,
286
+ * always https. The request is then `https://<host><pathTemplate>`; the base URL's path is not prepended, since it
287
+ * belongs to the base's host. Absent, which is the norm, the request is `<baseUrl><pathTemplate>`.
288
+ *
289
+ * Admitted only where the token the call already carries is valid: the connection's OAuth2 client declares
290
+ * `audiences`, and the audience that admits the base URL's host admits this host too. So no second token is minted
291
+ * and no token reaches a host outside its own resource ({@link describeProviderRestOperationHostDefect}). This is
292
+ * Google's shape: one grant serves every `*.googleapis.com` API, and a Gmail operation names `gmail.googleapis.com`
293
+ * on the one Google connection. Microsoft's Dataverse is not this shape: its token is a different audience's, so it
294
+ * stays a provider of its own sharing the connection.
295
+ */
296
+ readonly host?: string;
210
297
  readonly summary?: string;
211
298
  /**
212
299
  * Whether the operation MUTATES the vendor.
@@ -248,6 +335,8 @@ export interface ProviderRestOperation {
248
335
  * validates the string.
249
336
  */
250
337
  readonly responseDecoding?: ProviderRestResponseDecoding;
338
+ /** Required with `responseDecoding: BINARY`, refused with any other decoding (#2910). */
339
+ readonly binaryResponse?: ProviderRestBinaryResponse;
251
340
  /** Dot-path to the payload inside the response body. Absent = the body IS the payload. JSON answers only. */
252
341
  readonly resultPath?: string;
253
342
  readonly pagination?: ProviderRestOperationPagination;
@@ -278,10 +367,19 @@ export interface ProviderRestOperation {
278
367
  /** Narrows the provider's semantics for this one operation (a slow export, a tight endpoint). */
279
368
  readonly remoteCallSemantics?: Partial<ProviderRestCallSemantics>;
280
369
  /**
281
- * Where each input's choices come from, keyed by INPUT field name. Absent for an input a caller types.
282
- * See {@link ProviderRestOperationInputOptions}.
370
+ * Where each input's choices come from, keyed by a dot PATH into the input (#3399): `workspace` for a top-level
371
+ * field, `project.key` or `CustomerRef.value` for the value a vendor nests inside a reference object. Absent for an
372
+ * input a caller types. Every path must name a field of `inputSchema`
373
+ * ({@link describeProviderRestOperationInputOptionsDefects}). See {@link ProviderRestOperationInputOptions}.
283
374
  */
284
375
  readonly inputOptions?: Readonly<Record<string, ProviderRestOperationInputOptions>>;
376
+ /**
377
+ * Present for a GraphQL operation (#3392): the provider-owned document the call sends to `pathTemplate` (the vendor's
378
+ * GraphQL endpoint), with the operation's input as its variables. A 2xx answer carrying `errors` fails the call; the
379
+ * output is read from the answer's `data`. See {@link ProviderRestOperationGraphql} for what such an operation may and
380
+ * may not declare beside it.
381
+ */
382
+ readonly graphql?: ProviderRestOperationGraphql;
285
383
  /** Set when the vendor has deprecated it; the executor logs once per operation, never refuses. */
286
384
  readonly deprecated?: {
287
385
  readonly reason: string;
@@ -316,6 +414,377 @@ export interface ProviderRestOperationContributor {
316
414
  /** The installed version of that package, as `wildo config sync` read it from the manifest. */
317
415
  readonly packageVersion: string;
318
416
  }
417
+ /**
418
+ * How a vendor states, INSIDE a successful HTTP answer, whether the call it answered succeeded (#2661).
419
+ *
420
+ * Most vendors say it with the status: a 4xx or 5xx is a failure, and the transport already treats it as one. Some
421
+ * answer HTTP 200 for every call they could parse and put the verdict in the body. Slack's Web API is the case:
422
+ * "All Web API responses contain a JSON object, which will always contain a top-level boolean property `ok` that
423
+ * indicates success or failure", and "For failure results, the `error` property will contain a short machine-readable
424
+ * error code".
425
+ * spec-cite: https://docs.slack.dev/apis/web-api/ — "Evaluating responses", fetched 2026-10-06.
426
+ *
427
+ * Without this declaration such an answer reads as a success: `channel_not_found` is returned to the caller as if it
428
+ * were a posted message, the call's audit row says it succeeded, and a revoked token stays "accepted" on the
429
+ * credential. Declared on the provider's REST contract (`rest.applicationOutcome`), because the envelope is a fact
430
+ * about the vendor's API, not about one operation.
431
+ *
432
+ * Read for JSON answers only: an operation declaring `TEXT` or `NONE` decoding (a file download) has no envelope.
433
+ */
434
+ export interface ProviderRestApplicationOutcome {
435
+ /** Dot-path to the boolean the vendor sets `true` exactly when the call succeeded (Slack: `ok`). */
436
+ readonly successFlagPath: string;
437
+ /** Dot-path to the vendor's machine-readable error code on a failed call (Slack: `error`). */
438
+ readonly errorCodePath: string;
439
+ /**
440
+ * The error codes that mean the vendor refused the CREDENTIAL itself, rather than the request: the stored
441
+ * credential is then recorded as rejected, the way the vendor's answer said (Slack: `invalid_auth`,
442
+ * `account_inactive`, `token_revoked`, `token_expired`). A code that means the caller sent no credential at all
443
+ * (Slack's `not_authed`) does not belong here: that is our request's fault, not a dead credential.
444
+ */
445
+ readonly credentialRefusedErrorCodes?: readonly string[];
446
+ }
447
+ /** What a successful HTTP answer said about the call, read through a {@link ProviderRestApplicationOutcome}. */
448
+ export declare enum ProviderRestApplicationOutcomeKind {
449
+ /** The success flag is `true`. */
450
+ SUCCEEDED = "succeeded",
451
+ /** The success flag is `false`: the vendor refused the call, naming why at the error path when it could. */
452
+ REFUSED = "refused",
453
+ /** The flag is absent or not a boolean: the answer does not carry the envelope its provider declares. */
454
+ UNSTATED = "unstated"
455
+ }
456
+ /** The verdict a body carries. `errorCode` is kept only when it is a code-shaped string, never prose. */
457
+ export type ProviderRestApplicationOutcomeVerdict = {
458
+ readonly kind: ProviderRestApplicationOutcomeKind.SUCCEEDED;
459
+ } | {
460
+ readonly kind: ProviderRestApplicationOutcomeKind.REFUSED;
461
+ readonly errorCode?: string;
462
+ } | {
463
+ readonly kind: ProviderRestApplicationOutcomeKind.UNSTATED;
464
+ };
465
+ /**
466
+ * A vendor error code as the engine may carry it: identifier characters only, at most 128. A value of any other shape
467
+ * is dropped rather than carried, because it travels to audit rows, logs and API answers, and a vendor that puts a
468
+ * sentence (or request data) where a code belongs must not have it repeated there.
469
+ */
470
+ export declare const PROVIDER_VENDOR_ERROR_CODE_SHAPE: RegExp;
471
+ /**
472
+ * The defects of a declared outcome envelope, refused at boot: an empty path, and a credential-refusal code that is not
473
+ * code-shaped, which the transport would never carry and so would never match (#2661 review L7).
474
+ */
475
+ export declare function describeProviderRestApplicationOutcomeDefects(outcome: ProviderRestApplicationOutcome): string[];
476
+ /**
477
+ * The placeholder a client-credentials token URL may carry for the tenant the credential belongs to:
478
+ * `https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token`. Filled from the connection's
479
+ * {@link ProviderRestClientCredentials.tenantSecretRef} slot, never from a request.
480
+ */
481
+ export declare const PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER = "{tenant}";
482
+ /** A tenant value the token URL admits: a GUID or a DNS name. Nothing that can leave the URL's path segment. */
483
+ export declare const PROVIDER_CLIENT_CREDENTIALS_TENANT_SHAPE: RegExp;
484
+ /**
485
+ * The placeholder that BEGINS a client-credentials token URL whose token endpoint is on the deployment's own vendor
486
+ * instance (#3402): `{deploymentOrigin}/oauth2/v1/token`. Filled with the ORIGIN of the base URL the engine resolved for
487
+ * the REST contract (from `baseUrlHostEnvVarName` or `baseUrlEnvVarName`), never from a connection or a request.
488
+ *
489
+ * Okta is the case: every org has its own host (`<org>.okta.com`, or a custom domain), and its org authorization server's
490
+ * token endpoint is on that host. A fixed {@link ProviderRestClientCredentials.tokenHosts} list cannot admit a host only
491
+ * the operator knows, and a `{tenant}` value would be a second, separately typed copy of the host the operations already
492
+ * go to, which could disagree with it. Filling the token endpoint from the SAME resolved origin keeps them one value: the
493
+ * client's assertion is sent to the host the operator named, and to nothing a person connecting could choose.
494
+ *
495
+ * spec-cite: Okta Developer, "Implement OAuth for Okta with a service app"
496
+ * (https://developer.okta.com/docs/guides/implement-oauth-for-okta-serviceapp/main/, fetched 2026-11-10) — the token
497
+ * request is `POST https://{yourOktaDomain}/oauth2/v1/token`, and the assertion's `aud` is that URL.
498
+ */
499
+ export declare const PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER = "{deploymentOrigin}";
500
+ /** What a {@link ProviderClientCredentialsVerifiedFact} records: a value the person typed and the vendor accepted. */
501
+ export declare enum ProviderClientCredentialsFactSource {
502
+ /** The client id the token endpoint issued a token for: Microsoft's bot App ID. */
503
+ CLIENT_ID = "client_id",
504
+ /** The tenant whose token endpoint issued it. */
505
+ TENANT = "tenant"
506
+ }
507
+ /**
508
+ * One fact a client-credentials connection records once the vendor has accepted its credential. See
509
+ * {@link ProviderRestClientCredentials.verifiedAccountFacts}.
510
+ */
511
+ export interface ProviderClientCredentialsVerifiedFact {
512
+ readonly source: ProviderClientCredentialsFactSource;
513
+ /**
514
+ * `true` when the inbound receiver routes deliveries to an organization by this fact: an organization's own Teams
515
+ * bot, by its App ID (#2663). Such a fact may name ONE organization only, so a connect whose value another
516
+ * organization's enabled connection holds is refused, as for a vendor-reported fact.
517
+ */
518
+ readonly routesInboundDeliveries?: true;
519
+ /**
520
+ * `true` when the vendor treats the value without case, as Microsoft does an App ID or a tenant id (both GUIDs): the
521
+ * value is recorded LOWER-CASED, so a lookup by the vendor's own spelling (a token's `aud`) finds an id the
522
+ * administrator typed in capitals (#2663). Never for a value the vendor compares exactly, which most client ids are.
523
+ */
524
+ readonly caseInsensitive?: true;
525
+ }
526
+ /**
527
+ * A REST provider whose access token is minted with the OAuth 2.0 client-credentials grant, from a client id and
528
+ * secret the connection holds (#2663). The Bot Framework is the first: a Teams bot's App ID and secret, and for a
529
+ * single-tenant bot the tenant it is registered in, mint a token for `https://api.botframework.com/.default`.
530
+ *
531
+ * Declared beside `oauth2` (#3398), it is the APPLICATION's own connection: Box's client-credentials grant and Zoom's
532
+ * server-to-server OAuth renew the application's token while people and organizations connect through the exchange.
533
+ * {@link providerClientCredentialsServesOwnerScope} says which door a connection takes.
534
+ *
535
+ * The token is minted per call when no unexpired one is cached, never stored, and attached where
536
+ * {@link ProviderProtocolRuntimeContract}'s `apiKey` says, so (with no `oauth2` beside it) `apiKey.secretRef` names the
537
+ * client's credential, its SECRET or its private key (#3402), the slot whose absence means "not configured". The
538
+ * client id, credential and tenant are read from the connection: the
539
+ * application's own environment for an APPLICATION connection, the organization's typed credential for an
540
+ * ORGANIZATION one.
541
+ *
542
+ * The client id and tenant of an ORGANIZATION connection are typed by its administrator, so on their own they prove
543
+ * nothing. They become evidence when the vendor accepts them: at connect the engine mints a token with the typed
544
+ * values, refuses the connection when the vendor refuses, and records each {@link verifiedAccountFacts} entry as
545
+ * `VERIFIED_BY_VENDOR`. A bot App ID then routes deliveries only to the organization that holds its secret.
546
+ *
547
+ * spec-cite: RFC 6749 §4.4 — the client credentials grant (`grant_type=client_credentials`, client authentication,
548
+ * `scope`); Microsoft, "Authenticate requests with the Bot Connector API" — the single-tenant token request
549
+ * `POST https://login.microsoftonline.com/MICROSOFT-TENANT-ID/oauth2/v2.0/token` with the scope
550
+ * `https://api.botframework.com/.default`, fetched 2026-10-06.
551
+ */
552
+ export interface ProviderRestClientCredentials {
553
+ /**
554
+ * The https token endpoint. May carry {@link PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER}, or BEGIN with
555
+ * {@link PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER} when the token endpoint is on the deployment's own
556
+ * vendor instance (Okta's org, #3402).
557
+ */
558
+ readonly tokenUrl: string;
559
+ /**
560
+ * The hosts the token endpoint may be on once filled. The client secret is sent nowhere else. EMPTY exactly when the
561
+ * token URL begins with {@link PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER}: its host is the one the
562
+ * operator named for the operations, and no fixed list can name it.
563
+ */
564
+ readonly tokenHosts: readonly string[];
565
+ /**
566
+ * The `scope` parameter, sent as written. Omitted, no `scope` is sent: RFC 6749 makes it optional, and Box, Zoom and
567
+ * Salesforce grant the scopes configured on the app instead (#3398).
568
+ * spec-cite: RFC 6749 §4.4.2 — `scope`: "OPTIONAL. The scope of the access request as described by Section 3.3."
569
+ * Fetched 2026-10-06.
570
+ */
571
+ readonly scope?: string;
572
+ /**
573
+ * The `grant_type` sent. Omitted, `client_credentials` (RFC 6749 §4.4). See {@link ProviderClientCredentialsGrantType}.
574
+ */
575
+ readonly grantType?: ProviderClientCredentialsGrantType;
576
+ /**
577
+ * Further parameters of the token request a vendor requires, by name: a fixed value, or one read from a slot of the
578
+ * connection (#3398). Box's client-credentials grant names the subject it authenticates as (`box_subject_type`,
579
+ * `box_subject_id`); Zoom's server-to-server grant names the account (`account_id`). A parameter the grant itself
580
+ * defines (`grant_type`, `client_id`, `client_secret`, `scope`, the client assertion) is refused here: each has its own
581
+ * field. See {@link ProviderClientCredentialsTokenRequestParameter}.
582
+ */
583
+ readonly tokenRequestParameters?: Readonly<Record<string, ProviderClientCredentialsTokenRequestParameter>>;
584
+ /**
585
+ * How the client authenticates to the token endpoint. Omitted,
586
+ * {@link ProviderOAuth2ClientAuthenticationMethod.CLIENT_SECRET_POST} with a client secret: the id and secret in the
587
+ * body, as Microsoft's identity platform documents. {@link ProviderOAuth2ClientAuthenticationMethod.CLIENT_SECRET_BASIC}
588
+ * sends them in the Basic header only (Zoom's server-to-server OAuth documents nothing else). With
589
+ * {@link privateKeyJwt} the method is {@link ProviderOAuth2ClientAuthenticationMethod.PRIVATE_KEY_JWT}, implied when
590
+ * omitted (#3402).
591
+ */
592
+ readonly tokenEndpointAuthMethod?: ProviderOAuth2ClientAuthenticationMethod;
593
+ /** The slot holding the client id. */
594
+ readonly clientIdSecretRef: string;
595
+ /**
596
+ * The slot holding the client secret. Exactly one of this and {@link privateKeyJwt} (#3402): a client authenticates
597
+ * with a shared secret or with a key it alone holds, never both. The client's CREDENTIAL slot (this one, or the
598
+ * private key's) equals the contract's `apiKey.secretRef` when the contract declares no `oauth2` (the slot whose
599
+ * absence means "not configured"); beside `oauth2`, `apiKey.secretRef` is the slot of the people's and organizations'
600
+ * minted tokens and this one serves the application alone.
601
+ */
602
+ readonly clientSecretSecretRef?: string;
603
+ /**
604
+ * The client authenticates with a JWT it signs with its own private key (`private_key_jwt`, #3402) instead of a
605
+ * secret: Okta's OAuth service apps accept nothing else for the Management API. See
606
+ * {@link ProviderClientCredentialsPrivateKeyJwt}.
607
+ */
608
+ readonly privateKeyJwt?: ProviderClientCredentialsPrivateKeyJwt;
609
+ /** The slot filling {@link PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER}. Required exactly when the token URL carries it. */
610
+ readonly tenantSecretRef?: string;
611
+ /** Facts an ORGANIZATION connection records once the vendor accepted its credential, keyed by fact name. */
612
+ readonly verifiedAccountFacts?: Readonly<Record<string, ProviderClientCredentialsVerifiedFact>>;
613
+ /** Seconds a token is kept when the answer states no `expires_in`. Omitted, it is not cached. */
614
+ readonly tokenLifetimeFallbackSeconds?: number;
615
+ }
616
+ /**
617
+ * The `grant_type` a client-credentials token request sends. Narrower than `OAuth2_GrantType` on purpose: these are the
618
+ * grants the client-credentials minter performs, each with nothing but the client's own credential and the declared
619
+ * parameters, and a member joins in the change that implements it.
620
+ */
621
+ export declare enum ProviderClientCredentialsGrantType {
622
+ /**
623
+ * The OAuth 2.0 client-credentials grant: the default.
624
+ * spec-cite: RFC 6749 §4.4.2 — `grant_type`: "REQUIRED. Value MUST be set to "client_credentials"." Fetched 2026-10-06.
625
+ */
626
+ CLIENT_CREDENTIALS = "client_credentials",
627
+ /**
628
+ * Zoom's server-to-server OAuth: the same exchange (a client authenticated with Basic, one token back, no refresh
629
+ * token) under Zoom's own grant name, with the account named in `account_id`.
630
+ * spec-cite: https://developers.zoom.us/docs/internal-apps/s2s-oauth/ — "Use the `account_credentials` grant type to
631
+ * generate an access token."; "Set up the body of the access token request using the `account_credentials`
632
+ * `grant_type` and your `account_id`." Fetched 2026-11-09.
633
+ */
634
+ ACCOUNT_CREDENTIALS = "account_credentials"
635
+ }
636
+ /**
637
+ * One further parameter of a client-credentials token request ({@link ProviderRestClientCredentials.tokenRequestParameters}):
638
+ * a fixed `value` the module states (`box_subject_type: enterprise`), or a `secretRef` naming the connection slot that
639
+ * holds it (Box's enterprise id, Zoom's account id), read like the client id: from the application's environment for
640
+ * the application's connection, from the organization's credential for an organization's.
641
+ */
642
+ export type ProviderClientCredentialsTokenRequestParameter = {
643
+ readonly value: string;
644
+ readonly secretRef?: never;
645
+ } | {
646
+ readonly secretRef: string;
647
+ readonly value?: never;
648
+ };
649
+ /**
650
+ * The algorithms a client assertion is signed with (#3402). The JWS names (RFC 7518 §3.1) of the two asymmetric
651
+ * families every vendor measured accepts: Okta lists "RS256, RS384, RS512, ES256, ES384, and ES512" for a service app's
652
+ * key. A member joins when a vendor needs it.
653
+ * spec-cite: RFC 7518 §3.1 — "RS256 | RSASSA-PKCS1-v1_5 using SHA-256" and "ES256 | ECDSA using P-256 and SHA-256";
654
+ * https://developer.okta.com/docs/guides/implement-oauth-for-okta-serviceapp/main/ — the supported algorithms. Both
655
+ * fetched 2026-11-09.
656
+ */
657
+ export declare enum ProviderClientAssertionSigningAlgorithm {
658
+ /** ECDSA on P-256 with SHA-256: a short key and signature, and the default to choose for a new key. */
659
+ ES256 = "ES256",
660
+ /** RSASSA-PKCS1-v1_5 with SHA-256, for a vendor or key store that issues RSA keys. */
661
+ RS256 = "RS256"
662
+ }
663
+ /** The longest a client assertion may live: Okta refuses one whose `exp` is more than an hour away. */
664
+ export declare const PROVIDER_CLIENT_ASSERTION_MAXIMUM_LIFETIME_SECONDS = 3600;
665
+ /** How long a client assertion lives when the declaration says nothing: long enough for one request, and no more. */
666
+ export declare const PROVIDER_CLIENT_ASSERTION_DEFAULT_LIFETIME_SECONDS = 300;
667
+ /**
668
+ * `private_key_jwt` client authentication for a client-credentials token request (#3402). The client signs, per token
669
+ * request, a JWT whose `iss` and `sub` are its client id, whose `aud` is the token endpoint it is sent to, with a short
670
+ * `exp` and a fresh `jti`, and sends it as `client_assertion`.
671
+ *
672
+ * The private key is read from a slot of the connection, as an unencrypted PEM (PKCS#8, or an RSA PKCS#1 / EC key the
673
+ * signer re-wraps), like a secret: the application's configured provider secrets for its own connection, an organization's sealed
674
+ * credential row for an organization's.
675
+ *
676
+ * ## Why the platform keyring does not hold this key (decided 2026-11-10, #3402)
677
+ *
678
+ * The key layer (#2916) holds keys by PURPOSE, each signing the platform's own claims under its own `typ` and verified
679
+ * from public halves the platform publishes. A client key is the opposite: its public half is REGISTERED BY THE OPERATOR
680
+ * at the vendor (Okta's app, a Google service account), the vendor is its only verifier, and the vendor fixes the
681
+ * algorithm (Okta's console and Google's uploaded keys are RSA, while the keyring signs ES256 only). A keyring rotation
682
+ * would also silently break every connection whose vendor still holds the old public half. So custody signing for vendor
683
+ * clients is a key purpose of its own (RS256 across the keyring providers, a public half handed to the operator, rotation
684
+ * coordinated with the vendor registration), recorded on #2916, and not a missing step of this declaration.
685
+ *
686
+ * spec-cite: RFC 7523 §2.2 — "The value of the "client_assertion_type" is
687
+ * "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"."; §3 — the JWT "MUST contain an "iss" (issuer) claim", for
688
+ * client authentication "the subject MUST be the "client_id" of the OAuth client", an "aud" (audience) claim "containing
689
+ * a value that identifies the authorization server", and an "exp" (expiration time) claim; OpenID Connect Core 1.0 §9,
690
+ * `private_key_jwt` — `iss` and `sub` "MUST contain the client_id of the OAuth Client", "The Audience SHOULD be the URL
691
+ * of the Authorization Server's Token Endpoint", `jti` REQUIRED: "These tokens MUST only be used once". Fetched
692
+ * 2026-11-09 from https://www.rfc-editor.org/rfc/rfc7523 and https://openid.net/specs/openid-connect-core-1_0.html.
693
+ */
694
+ export interface ProviderClientCredentialsPrivateKeyJwt {
695
+ /** The slot holding the client's private key: an unencrypted PEM, PKCS#8 (`-----BEGIN PRIVATE KEY-----`) or PKCS#1 / EC. */
696
+ readonly privateKeySecretRef: string;
697
+ /** The JWS algorithm the key signs with. Must match the key: an EC P-256 key for ES256, an RSA key for RS256. */
698
+ readonly algorithm: ProviderClientAssertionSigningAlgorithm;
699
+ /**
700
+ * The slot holding the key id sent as the assertion's `kid` header, when the vendor locates the key by it (Okta
701
+ * requires a `kid` on every key registered with the app). Omitted, no `kid` is sent.
702
+ */
703
+ readonly keyIdSecretRef?: string;
704
+ /** Seconds until the assertion's `exp`. Omitted, {@link PROVIDER_CLIENT_ASSERTION_DEFAULT_LIFETIME_SECONDS}. */
705
+ readonly assertionLifetimeSeconds?: number;
706
+ }
707
+ /**
708
+ * The slot of a client-credentials declaration's own CREDENTIAL: the client secret, or the private key (#3402).
709
+ * `undefined` only for a declaration {@link describeProviderRestClientCredentialsDefects} refuses.
710
+ */
711
+ export declare function providerClientCredentialsCredentialSlot(credentials: ProviderRestClientCredentials): string | undefined;
712
+ /**
713
+ * The parameter names {@link ProviderRestClientCredentials.tokenRequestParameters} may not declare: each is written by
714
+ * the grant itself (the grant type, the client's credential, the scope, a client assertion), so a second value would
715
+ * either be ignored or override the declared one.
716
+ */
717
+ export declare const PROVIDER_CLIENT_CREDENTIALS_RESERVED_PARAMETER_NAMES: readonly string[];
718
+ /**
719
+ * Whether the client-credentials door of a REST contract serves a connection of this owner scope (#3398).
720
+ *
721
+ * Alone, it serves every admitted connection: the application's own (from its environment) and an organization's (from
722
+ * the credential the organization typed, as a Teams bot). Beside `oauth2`, a person or an organization connects through
723
+ * the authorization-code exchange, and the client-credentials grant serves the APPLICATION's own account only, so that
724
+ * account renews itself instead of resting on a pasted token that expires within the hour.
725
+ */
726
+ export declare function providerClientCredentialsServesOwnerScope(contract: {
727
+ readonly clientCredentials?: ProviderRestClientCredentials;
728
+ readonly oauth2?: unknown;
729
+ }, ownerScope: ExternalProvider_Connection_OwnerScope): boolean;
730
+ /**
731
+ * The slot a connection of this owner scope AUTHENTICATES with, as the engine's REST access resolver reads it: the
732
+ * client-credentials grant's own credential (its client secret or private key) when that door serves the owner scope
733
+ * ({@link providerClientCredentialsServesOwnerScope}), else `apiKey.secretRef`, the stored or pasted token itself.
734
+ *
735
+ * For a contract declaring `clientCredentials` beside `oauth2` (Box, Zoom, #3398) the two differ by owner: the
736
+ * application's own account mints from the server app's secret, while a person's connection reads its exchanged token
737
+ * from `apiKey.secretRef`. A tool standing in for one connection (`wildo providers probe`, `connect`, the doctor's
738
+ * configuration checks, all APPLICATION-owned) asks this instead of reading `apiKey.secretRef`, so it reads the slot the
739
+ * engine would. `undefined` when the contract names neither.
740
+ */
741
+ export declare function providerRestConnectionCredentialSlot(contract: {
742
+ readonly clientCredentials?: ProviderRestClientCredentials;
743
+ readonly oauth2?: unknown;
744
+ readonly apiKey?: {
745
+ readonly secretRef?: string;
746
+ };
747
+ }, ownerScope: ExternalProvider_Connection_OwnerScope): string | undefined;
748
+ /**
749
+ * Why a client-credentials declaration cannot be honoured, or an empty list. Checked where a provider is composed:
750
+ * 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
751
+ * with no tenant slot (or the reverse), or any other placeholder in the URL.
752
+ */
753
+ export declare function describeProviderRestClientCredentialsDefects(credentials: ProviderRestClientCredentials): string[];
754
+ /**
755
+ * Why a REST contract's `clientCredentials` sits wrongly beside the contract's other authentication fields, or an empty
756
+ * list (#2663, #3398). Checked where a provider is composed, beside {@link describeProviderRestClientCredentialsDefects}.
757
+ *
758
+ * - beside `requestSigning`: two ways to authenticate one call;
759
+ * - alone, `apiKey.secretRef` must be the client secret's slot, the one whose absence means "not configured";
760
+ * - beside `oauth2` the grant serves the APPLICATION's own account only ({@link providerClientCredentialsServesOwnerScope}),
761
+ * so the module must admit that connection; `apiKey.secretRef` names the exchanged tokens' slot and may not be the
762
+ * client secret's (a person's token would be read from it); and `verifiedAccountFacts`, which only an organization's
763
+ * connection records, would record nothing.
764
+ * - a token URL on {@link PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER} (#3402) needs a base URL the
765
+ * DEPLOYMENT names (`baseUrlHostEnvVarName` or `baseUrlEnvVarName`), and may serve the APPLICATION's connection only:
766
+ * the deployment's instance is the application's own (its Okta org), so an organization minting there would
767
+ * authenticate against the application's vendor tenant, never its own.
768
+ */
769
+ export declare function describeProviderRestClientCredentialsPlacementDefects(contract: {
770
+ readonly clientCredentials?: ProviderRestClientCredentials;
771
+ readonly oauth2?: unknown;
772
+ readonly requestSigning?: unknown;
773
+ readonly apiKey: {
774
+ readonly secretRef: string;
775
+ };
776
+ readonly baseUrlHostEnvVarName?: string;
777
+ readonly baseUrlEnvVarName?: string;
778
+ }, admitsApplicationConnection: boolean,
779
+ /** Whether the module admits an ORGANIZATION or USER connection. Omitted, `false`. */
780
+ admitsNonApplicationConnection?: boolean): string[];
781
+ /**
782
+ * The vendor's error code at `errorCodePath` in a parsed answer, when it is code-shaped. Used for a refused 2xx and for
783
+ * a non-2xx answer alike: a vendor that states its code in the body states it in the same place whatever the status.
784
+ */
785
+ export declare function readProviderVendorErrorCode(body: unknown, errorCodePath: string): string | undefined;
786
+ /** Reads the verdict a parsed JSON answer carries. The ONE reader: the transport and every test go through it. */
787
+ export declare function readProviderRestApplicationOutcome(body: unknown, outcome: Pick<ProviderRestApplicationOutcome, 'successFlagPath' | 'errorCodePath'>): ProviderRestApplicationOutcomeVerdict;
319
788
  /** @wildo_source:part:end external-connectors.models.rest-operation-contract */
320
789
  /**
321
790
  * The lazy catalogue loader — the seam #330's host loader consumes (interface note on #331).
@@ -330,6 +799,25 @@ export interface ProviderRestOperationContributor {
330
799
  * never serializable into a runtime artifact or any JSON the CLI emits.
331
800
  */
332
801
  export type ProviderRestOperationCatalogueLoader = (domain?: string) => Promise<ProviderRestOperationCatalogue>;
802
+ /**
803
+ * The QUERY parameters an operation declares under a name its provider places a credential in, compared IGNORING CASE
804
+ * (#2123, #2707). Empty when there is none.
805
+ *
806
+ * Such a parameter asks the caller for the credential the contract already places, so the operation would send the key
807
+ * twice, or send the caller's value instead of the configured one. A name differing only in case travels BESIDE the
808
+ * credential, and a vendor that reads names without regard to case may read the caller's value. Both are a declaration
809
+ * defect.
810
+ *
811
+ * ONE comparison for every place that refuses it, so they cannot drift apart:
812
+ * - the operation executor, once per catalogue load, against the contract's `apiKey.queryParameterName`;
813
+ * - the operation request builder, on every call, against the resolved access's query-placed names (the backstop for a
814
+ * placement that does not come from the contract);
815
+ * - `wildo` registry module checks, at publish, against the module's own contract.
816
+ *
817
+ * A PATH or HEADER parameter is not compared: a path token is a resource id that may merely be spelled like a
818
+ * credential, and a header credential is refused by its own placement rules.
819
+ */
820
+ export declare function providerRestOperationCredentialQueryParameters(operation: Pick<ProviderRestOperation, 'parameters'>, credentialQueryParameterNames: Iterable<string>): string[];
333
821
  /**
334
822
  * Provider-level call semantics: the defaults every operation of this provider runs under.
335
823
  *
@@ -501,8 +989,108 @@ export interface ProviderRestOAuth2 {
501
989
  *
502
990
  * Absent — not empty — when no revocation is declared, so "this vendor cannot be told" stays
503
991
  * distinguishable from "nobody has looked".
992
+ *
993
+ * The client authenticates here exactly as it does at the token endpoint ({@link tokenEndpointAuthMethod}), and the
994
+ * body is form-encoded unless {@link revocationRequestBodyEncoding} says otherwise: a vendor that takes RFC 7009's
995
+ * `token` parameter and answers its 200, but wants Basic or a JSON body, is still declared here.
504
996
  */
505
997
  readonly rfc7009RevocationUrl?: string;
998
+ /**
999
+ * The vendor's USERINFO endpoint (#3397): a GET carrying the access token the authorization just minted as a Bearer
1000
+ * credential, whose JSON answer is read by every fact declared with
1001
+ * {@link ProviderOAuth2ReportedFactSource.USERINFO_RESPONSE}. DocuSign names the connected account and its API host
1002
+ * nowhere else: `GET https://account(-d).docusign.com/oauth/userinfo` lists the person's `accounts`, each with its
1003
+ * `account_id` and `base_uri`.
1004
+ *
1005
+ * Called ONCE, at the authorization-code exchange that makes (or remakes) the connection, and only when some fact
1006
+ * reads it; never at a refresh. The vendor's own guidance is to call it at setup and store the answer, and DocuSign
1007
+ * enforces an hourly limit on these requests per user and per integration key, so a call per refresh would spend that
1008
+ * limit to restate facts that change "very infrequently".
1009
+ * spec-cite: DocuSign, "UserInfo" (https://developers.docusign.com/platform/auth/reference/user-info/, fetched
1010
+ * 2026-11-09) — "Your integration should call this method to get the information needed to begin making API calls
1011
+ * during setup, then store it for use in future calls" and "Docusign enforces hourly limits on the number of
1012
+ * `/oauth/userinfo` requests per user ID and per integration key".
1013
+ *
1014
+ * Resolved like {@link tokenUrl}, through the same {@link endpointHostAllowances} and deployment values, because it
1015
+ * receives a credential too (the person's access token). It belongs to the same authorization server, so it may carry
1016
+ * only the host-forming placeholders the token endpoint carries, each in the same position
1017
+ * ({@link describeProviderOAuth2ReportedFactUseDefects}); every reader of "which placeholders does this client have"
1018
+ * therefore stays complete reading the authorize and token endpoints alone. A redirect is refused, never followed.
1019
+ */
1020
+ readonly userInfoUrl?: string;
1021
+ /**
1022
+ * How the client authenticates to the vendor's token endpoint: at the code exchange, at every refresh (and every
1023
+ * per-audience mint, which is a refresh), and at the revocation endpoint. Named after the client metadata field
1024
+ * `token_endpoint_auth_method`, whose values it uses. See {@link ProviderOAuth2ClientAuthenticationMethod}.
1025
+ *
1026
+ * Absent means {@link ProviderOAuth2ClientAuthenticationMethod.CLIENT_SECRET_POST}: `client_id` and `client_secret` in
1027
+ * the body, the engine's behaviour before this field existed, so no existing provider sends a different byte. Declare
1028
+ * {@link ProviderOAuth2ClientAuthenticationMethod.CLIENT_SECRET_BASIC} for a vendor that documents the Basic header
1029
+ * (Zoom, Notion, Intuit). With Basic the body carries neither `client_id` nor `client_secret`: the header identifies
1030
+ * the client, and a credential is sent on one channel only.
1031
+ * spec-cite: RFC 6749 §4.1.3 — `client_id` is "REQUIRED, if the client is not authenticating with the authorization
1032
+ * server" as Section 3.2.1 describes. Fetched 2026-11-06.
1033
+ *
1034
+ * ## Why the revocation endpoint does not get a method of its own
1035
+ *
1036
+ * RFC 7009 sends the client's credentials at the revocation endpoint "as described in Section 2.3. of [RFC6749]", the
1037
+ * same section as the token endpoint, and every vendor measured on 2026-11-06 (Zoom, Notion, Intuit) authenticates
1038
+ * both endpoints the same way. A separate member would be a choice no vendor has needed; it is added when one does.
1039
+ * spec-cite: RFC 7009 §2.1 — "The client also includes its authentication credentials as described in Section 2.3.
1040
+ * of [RFC6749]." Fetched 2026-11-06.
1041
+ */
1042
+ readonly tokenEndpointAuthMethod?: ProviderOAuth2ClientAuthenticationMethod;
1043
+ /**
1044
+ * How the token request's parameters are written (exchange, refresh, per-audience mint). Absent means
1045
+ * {@link ProviderOAuth2RequestBodyEncoding.FORM}, as RFC 6749 specifies. Notion's token endpoint takes JSON only.
1046
+ */
1047
+ readonly tokenRequestBodyEncoding?: ProviderOAuth2RequestBodyEncoding;
1048
+ /**
1049
+ * Extra parameters the AUTHORIZATION-CODE exchange carries beside the specification's own (follow-up to #3392), each a
1050
+ * fixed value the provider module owns: a vendor that issues a different kind of token when asked in the exchange.
1051
+ * Shopify issues an expiring offline token (an hour, with a refresh token) only when the exchange carries `expiring=1`,
1052
+ * and a non-expiring one otherwise; a public app on non-expiring tokens is refused from April 2027.
1053
+ * spec-cite: https://shopify.dev/docs/apps/build/authentication-authorization/access-tokens — the `expiring` row: "Set
1054
+ * to `1` for an expiring offline token, or `0` (default) for a non-expiring one.", fetched 2026-11-10.
1055
+ *
1056
+ * Sent at the code exchange only: a refresh renews the grant the exchange made and Shopify's refresh request carries no
1057
+ * such parameter. A name the engine writes itself (`grant_type`, `code`, `redirect_uri`, `code_verifier`, the client's
1058
+ * credentials, `refresh_token`, `scope`) is refused, so a declaration cannot change what the exchange is
1059
+ * ({@link describeProviderOAuth2TokenRequestDefects}).
1060
+ *
1061
+ * @example
1062
+ * codeExchangeParameters: { expiring: '1' }
1063
+ */
1064
+ readonly codeExchangeParameters?: Readonly<Record<string, string>>;
1065
+ /**
1066
+ * The refusals of a REFRESH that the vendor documents as a dead refresh token, beside the specification's
1067
+ * `invalid_grant` (follow-up to #3392). A refresh refused with one of them retires the stored connection the way
1068
+ * `invalid_grant` does, rather than being retried at every call. Shopify answers a refresh token that can no longer be
1069
+ * used with `invalid_request` and a fixed description, and says to treat it as final.
1070
+ * spec-cite: https://shopify.dev/docs/api/usage/response-codes — "A refresh token that can no longer be used returns this
1071
+ * status with the error code `invalid_request` and the description `This request requires an active refresh_token`.
1072
+ * Treat it as final rather than retrying.", fetched 2026-11-10.
1073
+ *
1074
+ * `error` is the OAuth2 `error` code. `errorDescription`, when given, must equal the answer's `error_description`
1075
+ * exactly: `invalid_request` alone also names a malformed request, which says nothing about the person's grant, so a
1076
+ * vendor that reuses a generic code is matched on its description too. Read at a refresh only, never at the exchange.
1077
+ * `invalid_client` is refused: it names the APPLICATION's registration, and retiring every connection over it would
1078
+ * blame the people who connected (see `providerOAuth2GrantWasPermanentlyRejected`).
1079
+ *
1080
+ * @example
1081
+ * refreshRefusals: [{ error: 'invalid_request', errorDescription: 'This request requires an active refresh_token' }]
1082
+ */
1083
+ readonly refreshRefusals?: readonly ProviderOAuth2RefreshRefusal[];
1084
+ /**
1085
+ * How the revocation request's parameters are written. Absent means {@link ProviderOAuth2RequestBodyEncoding.FORM}, as
1086
+ * RFC 7009 specifies, whatever {@link tokenRequestBodyEncoding} says: the two encodings are declared separately because
1087
+ * a vendor can differ between its two endpoints. Intuit's own client library form-encodes the token request and sends
1088
+ * the revocation request as JSON.
1089
+ * spec-cite: intuit/oauth-jsclient `OAuthClient.prototype.revoke` and `_tokenRequestHeaders`
1090
+ * (https://raw.githubusercontent.com/intuit/oauth-jsclient/e65c49b0fd1c5356ba24ddbbe910b8bc71b6f75f/src/OAuthClient.js,
1091
+ * fetched 2026-11-06).
1092
+ */
1093
+ readonly revocationRequestBodyEncoding?: ProviderOAuth2RequestBodyEncoding;
506
1094
  /**
507
1095
  * Scopes the vendor's own catalogue entry asked for. An application may request FEWER (a subset of
508
1096
  * these, once resolved), and an operation's `requiredScopes` is the finer statement. Kept because
@@ -533,6 +1121,40 @@ export interface ProviderRestOAuth2 {
533
1121
  * set ACCUMULATES the previous consent with the new answer.
534
1122
  */
535
1123
  readonly incrementalConsent?: ProviderOAuth2IncrementalConsent;
1124
+ /**
1125
+ * How this vendor is asked for a refresh token, when it is an authorize-request PARAMETER rather than a scope (#2546).
1126
+ * See {@link ProviderOAuth2OfflineAccess}. Absent means the vendor needs no parameter: it issues a refresh token to
1127
+ * every authorization code, or asks for it through a scope the provider lists in `scopes` (Microsoft's
1128
+ * `offline_access`).
1129
+ */
1130
+ readonly offlineAccess?: ProviderOAuth2OfflineAccess;
1131
+ /**
1132
+ * How the token answer's `scope` lists what was granted, when it is not the specification's space-delimited list
1133
+ * (#2546). Absent means RFC 6749's encoding. Read only from the answer; the request is {@link authorizeScopesDelimiter}.
1134
+ */
1135
+ readonly grantedScopesDelimiter?: ProviderOAuth2ScopeListDelimiter;
1136
+ /**
1137
+ * How the AUTHORIZE request's `scope` must list the scopes asked for, when the vendor does not take the specification's
1138
+ * space-delimited list (#2661). Absent means RFC 6749's encoding, which most vendors accept even when their token
1139
+ * answer uses another (GitHub). Slack documents commas for the request: "a comma-separated list of scopes, such as:
1140
+ * `scope=incoming-webhook,commands`".
1141
+ * spec-cite: https://docs.slack.dev/authentication/installing-with-oauth — the authorize step, fetched 2026-10-06.
1142
+ */
1143
+ readonly authorizeScopesDelimiter?: ProviderOAuth2ScopeListDelimiter;
1144
+ /**
1145
+ * Whether the vendor accepts PKCE from this application's (confidential) client (#2661). Absent means
1146
+ * {@link ProviderOAuth2PkceSupport.S256}: the authorize request carries an S256 `code_challenge` and the code exchange its
1147
+ * `code_verifier`, which RFC 9700 recommends for every client and every vendor that ignores unknown parameters accepts.
1148
+ *
1149
+ * {@link ProviderOAuth2PkceSupport.NOT_ACCEPTED} is a vendor that REFUSES PKCE unless the application registered as a public
1150
+ * client: Slack answers `pkce_not_allowed` ("The app is not allowed to use the PKCE flow"), and turning PKCE on there
1151
+ * is irreversible ("Enabling PKCE marks your app as a public client, which is is a one-way operation"), drops the
1152
+ * client secret, and makes every refresh token expire in 30 days. The install then relies on `state`, the exact
1153
+ * `redirect_uri` and the client secret at the exchange, which is what a confidential client has without PKCE.
1154
+ * spec-cite: https://docs.slack.dev/reference/methods/oauth.v2.access — the `pkce_not_allowed` row, and
1155
+ * https://docs.slack.dev/authentication/using-pkce — the quoted sentence, both fetched 2026-10-06.
1156
+ */
1157
+ readonly pkce?: ProviderOAuth2PkceSupport;
536
1158
  /**
537
1159
  * Scopes a person cannot grant for themselves: only an administrator of the account can (#1671). Microsoft's
538
1160
  * application permissions and its admin-restricted delegated permissions are the case — "Application permissions
@@ -594,7 +1216,8 @@ export interface ProviderRestOAuth2 {
594
1216
  *
595
1217
  * ## Why this exists: the token endpoint receives the application's client secret
596
1218
  *
597
- * The exchange POSTs `client_id` and the APPLICATION's `client_secret` to the resolved `tokenUrl`.
1219
+ * The exchange sends `client_id` and the APPLICATION's `client_secret` to the resolved `tokenUrl`, in the body or in a
1220
+ * Basic header ({@link ProviderRestOAuth2.tokenEndpointAuthMethod}); either way the host receives the secret.
598
1221
  * Until 2026-09-12 every placeholder was answered from the connect-start request body, so where a
599
1222
  * placeholder formed the HOST — Microsoft's `https://{cloud}/…/token`, Salesforce's
600
1223
  * `https://{environment}/…`, Zoho's `https://accounts.{location}/…` — any user allowed to start a
@@ -657,6 +1280,28 @@ export interface ProviderRestOAuth2 {
657
1280
  * re-checked on every call that uses it.
658
1281
  */
659
1282
  readonly reportedAccountFacts?: Readonly<Record<string, ProviderOAuth2ReportedAccountFact>>;
1283
+ /**
1284
+ * Conditions the ID token of the sign-in that makes a connection must meet (#2663), every one of them, or the
1285
+ * connect is refused before anything is stored. See {@link ProviderOAuth2IdTokenRequirement}. Needs `openid` among
1286
+ * {@link scopes}.
1287
+ */
1288
+ readonly idTokenRequirements?: readonly ProviderOAuth2IdTokenRequirement[];
1289
+ /**
1290
+ * The issuer (`iss`) an ID token this client reads claims from must name (#2663 re-review I1). Required when it reads
1291
+ * any: an {@link idTokenRequirements} entry, or a {@link reportedAccountFacts} fact sourced from ID token claims.
1292
+ *
1293
+ * A claim is used only from a token that names this issuer, names this client as its only audience (`aud`), and has
1294
+ * not expired (`exp`): the checks OpenID Connect requires of a client. A token listing any other audience is refused
1295
+ * too, since a client trusts no audience but itself unless it says so, and nothing here says so. Only the signature
1296
+ * check may be replaced by TLS, which is the one this exchange relies on. A `{claim}` placeholder is filled from the token's own claims, for
1297
+ * an issuer that varies per tenant: Microsoft's multi-tenant `https://login.microsoftonline.com/{tid}/v2.0`.
1298
+ * spec-cite: OpenID Connect Core 1.0 §3.1.3.7, items 2 ("MUST exactly match the value of the iss (issuer) Claim"),
1299
+ * 3 ("MUST validate that the aud (audience) Claim contains its client_id"; "The ID Token MUST be rejected if the ID
1300
+ * Token does not list the Client as a valid audience, or if it contains additional audiences not trusted by the
1301
+ * Client"), 6 (TLS in place of the signature) and 9
1302
+ * ("The current time MUST be before the time represented by the exp Claim").
1303
+ */
1304
+ readonly idTokenIssuer?: string;
660
1305
  /**
661
1306
  * The RESOURCE AUDIENCES one grant of this client can mint tokens for, keyed by audience id (#1725), and the
662
1307
  * HOSTS a token of each may be sent to.
@@ -687,10 +1332,33 @@ export interface ProviderRestOAuth2 {
687
1332
  readonly audiences?: Readonly<Record<string, ProviderRestOAuth2Audience>>;
688
1333
  /** The audience the authorization itself grants — see {@link audiences}. Required when `audiences` is declared. */
689
1334
  readonly primaryAudience?: string;
1335
+ /**
1336
+ * What this vendor's URI scopes NAME (#2546) — see {@link ProviderOAuth2ScopeMeaning}. Read only with `audiences`:
1337
+ * it decides which audience a scope belongs to. Absent means {@link ProviderOAuth2ScopeMeaning.RESOURCE}, Microsoft's
1338
+ * model, where `https://graph.microsoft.com/Mail.Send` is a permission ON the Graph resource.
1339
+ */
1340
+ readonly scopeMeaning?: ProviderOAuth2ScopeMeaning;
690
1341
  }
691
1342
  /** @wildo_source:part:start external-connectors.models.oauth2-audiences facet:layer:shared facet:family:provider facet:audience:app-developer */
692
1343
  /** The placeholder a {@link ProviderRestOAuth2Audience.mintScopes} entry uses for the https origin of the request's host. */
693
1344
  export declare const PROVIDER_OAUTH2_AUDIENCE_ORIGIN_PLACEHOLDER = "{audienceOrigin}";
1345
+ /** What a vendor's URI scopes name, which decides the audience a scope belongs to — see {@link ProviderRestOAuth2.scopeMeaning}. */
1346
+ export declare enum ProviderOAuth2ScopeMeaning {
1347
+ /**
1348
+ * A URI scope names the RESOURCE a token is minted for: the scope without its last path segment
1349
+ * (`https://graph.microsoft.com/Mail.Send` is Graph's). Microsoft's model, and the default.
1350
+ */
1351
+ RESOURCE = "RESOURCE",
1352
+ /**
1353
+ * A URI scope names a PERMISSION of the vendor's one grant, not a resource: Google's scopes are URIs on several hosts
1354
+ * (`https://www.googleapis.com/auth/gmail.readonly`, `https://mail.google.com/`, `https://spreadsheets.google.com/feeds`)
1355
+ * and every one is consented on the same grant, whose one token serves every Google API. So every scope belongs to the
1356
+ * PRIMARY audience, whatever host its URI names. Declared with a single audience only.
1357
+ * spec-cite: https://developers.google.com/identity/protocols/oauth2/scopes — the scope tables, which list both forms
1358
+ * (fetched 2026-10-05).
1359
+ */
1360
+ PERMISSION = "PERMISSION"
1361
+ }
694
1362
  /** One resource audience of a connection's grant. See {@link ProviderRestOAuth2.audiences}. */
695
1363
  export interface ProviderRestOAuth2Audience {
696
1364
  /**
@@ -700,6 +1368,12 @@ export interface ProviderRestOAuth2Audience {
700
1368
  readonly hosts: {
701
1369
  readonly values: readonly string[];
702
1370
  readonly hostSuffixes?: readonly string[];
1371
+ /**
1372
+ * The most DNS labels a host may carry before one of `hostSuffixes`; absent, any number (#3640). The same bound,
1373
+ * with the same meaning, as a host allowance's `hostSuffixMaxLabels`: declare it where the vendor documents its
1374
+ * hosts as one shape (`<store>.myshopify.com`), so a token is never sent to a deeper name under the suffix.
1375
+ */
1376
+ readonly hostSuffixMaxLabels?: number;
703
1377
  };
704
1378
  /**
705
1379
  * The scopes that mint a token for this audience, all of ONE resource. An entry may begin with
@@ -719,13 +1393,18 @@ export interface ProviderOAuth2AudienceSelection {
719
1393
  readonly audience: ProviderRestOAuth2Audience;
720
1394
  readonly primary: boolean;
721
1395
  }
722
- /** Whether `host` is admitted by one audience's hosts: an exact value, or `<labels><suffix>` for a declared suffix. */
1396
+ /**
1397
+ * Whether `host` is admitted by one audience's hosts: an exact value, or `<labels><suffix>` for a declared suffix, with
1398
+ * no more labels than `hostSuffixMaxLabels` allows (#3640).
1399
+ */
723
1400
  export declare function providerOAuth2AudienceAdmitsHost(audience: ProviderRestOAuth2Audience, host: string): boolean;
724
1401
  /**
725
1402
  * The ONE audience whose hosts admit `host`, or `undefined` when none does. The declaration guarantees at most one
726
1403
  * ({@link describeProviderOAuth2AudienceDefects} refuses overlapping hosts), so the answer never depends on order.
727
1404
  */
728
1405
  export declare function selectProviderOAuth2AudienceForHost(oauth2: Pick<ProviderRestOAuth2, 'audiences' | 'primaryAudience'>, host: string): ProviderOAuth2AudienceSelection | undefined;
1406
+ /** Whether `audience` mints its token per request ORIGIN (a mint scope beginning {@link PROVIDER_OAUTH2_AUDIENCE_ORIGIN_PLACEHOLDER}). */
1407
+ export declare function providerOAuth2AudienceIsOriginScoped(audience: Pick<ProviderRestOAuth2Audience, 'mintScopes'>): boolean;
729
1408
  /**
730
1409
  * The scopes that mint `audience`'s token for a request to `origin` — `{audienceOrigin}` replaced by that origin.
731
1410
  * The caller has already admitted the origin's host through {@link selectProviderOAuth2AudienceForHost}; nothing a
@@ -745,7 +1424,7 @@ export declare function resolveProviderOAuth2AudienceMintScopes(audience: Provid
745
1424
  * spec-cite: https://learn.microsoft.com/en-us/entra/identity-platform/consent-types-developer — the note under
746
1425
  * "Admin Consent for Delegated Permissions", fetched 2026-09-27.
747
1426
  */
748
- export declare function findProviderOAuth2ScopeAudience(oauth2: Pick<ProviderRestOAuth2, 'audiences' | 'primaryAudience'>, scope: string): string | undefined;
1427
+ export declare function findProviderOAuth2ScopeAudience(oauth2: Pick<ProviderRestOAuth2, 'audiences' | 'primaryAudience' | 'scopeMeaning'>, scope: string): string | undefined;
749
1428
  /**
750
1429
  * Whether a scope a connection might REQUEST names a resource among the connection's declared audiences (#1671) — see
751
1430
  * {@link findProviderOAuth2ScopeAudience}. Asking a person to consent to it is asking them to let this application reach
@@ -753,7 +1432,16 @@ export declare function findProviderOAuth2ScopeAudience(oauth2: Pick<ProviderRes
753
1432
  * the connection declares. `true` without looking further when the connection declares no audiences: it mints one token
754
1433
  * for one resource and its scopes are the vendor's own vocabulary (Google's scope URIs name permissions, not resources).
755
1434
  */
756
- export declare function providerOAuth2ScopeNamesDeclaredAudience(oauth2: Pick<ProviderRestOAuth2, 'audiences' | 'primaryAudience'>, scope: string): boolean;
1435
+ export declare function providerOAuth2ScopeNamesDeclaredAudience(oauth2: Pick<ProviderRestOAuth2, 'audiences' | 'primaryAudience' | 'scopeMeaning'>, scope: string): boolean;
1436
+ /**
1437
+ * Why an operation's {@link ProviderRestOperation.host} cannot be used on a provider whose REST binding is `contract`, or
1438
+ * `undefined` when it can (#2546). The token a call carries is chosen by the base URL's host, so the operation's host
1439
+ * must belong to that same audience: then the same token is valid there and nothing is minted for it.
1440
+ */
1441
+ export declare function describeProviderRestOperationHostDefect(host: string, contract: {
1442
+ readonly baseUrl?: string;
1443
+ readonly oauth2?: Pick<ProviderRestOAuth2, 'audiences' | 'primaryAudience'>;
1444
+ }): string | undefined;
757
1445
  /** @wildo_source:part:end external-connectors.models.oauth2-audiences */
758
1446
  /** @wildo_source:part:start external-connectors.models.oauth2-incremental-consent facet:layer:shared facet:family:provider facet:audience:app-developer */
759
1447
  /**
@@ -777,6 +1465,167 @@ export declare enum ProviderOAuth2IncrementalConsentForm {
777
1465
  */
778
1466
  INCLUDE_GRANTED_SCOPES = "INCLUDE_GRANTED_SCOPES"
779
1467
  }
1468
+ /**
1469
+ * How a vendor is asked for a refresh token, when a scope does not do it — see {@link ProviderRestOAuth2.offlineAccess}.
1470
+ */
1471
+ export declare enum ProviderOAuth2OfflineAccessForm {
1472
+ /**
1473
+ * Google: the authorize request carries `access_type=offline`, without which no refresh token is issued. The parameter
1474
+ * "Indicates whether your application can refresh access tokens when the user is not present at the browser. Valid
1475
+ * parameter values are `online`, which is the default value, and `offline`."; and "the refresh token is only returned
1476
+ * if your application set the `access_type` parameter to `offline`".
1477
+ * spec-cite: https://developers.google.com/identity/protocols/oauth2/web-server — Step 1 (`access_type` row) and
1478
+ * Step 5, fetched 2026-10-05.
1479
+ *
1480
+ * Google issues the refresh token at the FIRST exchange for a consent, so a request that does not grow an existing grant
1481
+ * (a first connect, or a reconnect replacing a grant) also carries `prompt=consent`: a reconnect of an account that had
1482
+ * already consented would otherwise store a grant with no refresh token, which expires within the hour. A request that
1483
+ * grows a grant (`include_granted_scopes`) does not need it, because the stored grant keeps its refresh token.
1484
+ * Decided by practice: the established Google integrations ask for `access_type=offline` with `prompt=consent` for
1485
+ * exactly this reason.
1486
+ */
1487
+ ACCESS_TYPE_OFFLINE = "ACCESS_TYPE_OFFLINE"
1488
+ }
1489
+ /** Whether a vendor takes PKCE from a confidential client. See {@link ProviderRestOAuth2.pkce}. */
1490
+ export declare enum ProviderOAuth2PkceSupport {
1491
+ /** An S256 challenge on the authorize request and its verifier on the exchange: the default. */
1492
+ S256 = "S256",
1493
+ /** The vendor refuses PKCE from a confidential client (Slack): neither is sent. */
1494
+ NOT_ACCEPTED = "NOT_ACCEPTED"
1495
+ }
1496
+ /**
1497
+ * How this application's client authenticates to a vendor's token and revocation endpoints. See
1498
+ * {@link ProviderRestOAuth2.tokenEndpointAuthMethod}.
1499
+ *
1500
+ * The values are the names the "OAuth Token Endpoint Authentication Methods" registry gives these two methods, which
1501
+ * is what OpenID Connect and dynamic client registration call `token_endpoint_auth_method`, so a vendor's discovery
1502
+ * document (`token_endpoint_auth_methods_supported`) can be compared with a declaration by eye.
1503
+ * spec-cite: RFC 7591 §2 — `token_endpoint_auth_method`: "client_secret_post": "The client uses the HTTP POST parameters
1504
+ * as defined in OAuth 2.0, Section 2.3.1."; "client_secret_basic": "The client uses HTTP Basic as defined in OAuth 2.0,
1505
+ * Section 2.3.1." Fetched 2026-11-06.
1506
+ *
1507
+ * Narrower than `OAuth2_TokenEndpoint_AuthMethod` on purpose: that vocabulary also names `client_secret_jwt` and
1508
+ * `none`, which nothing here performs. `private_key_jwt` joined with #3402, performed by the client-credentials grant
1509
+ * only; the connected-account exchange refuses it at startup. A member nothing honours would
1510
+ * be a declaration that looks like a client-authentication choice and changes nothing, so each method joins this
1511
+ * vocabulary in the change that implements it.
1512
+ */
1513
+ export declare enum ProviderOAuth2ClientAuthenticationMethod {
1514
+ /**
1515
+ * `client_id` and `client_secret` as parameters of the request body: the engine's behaviour when nothing is declared,
1516
+ * and what most vendors' own documentation shows. RFC 6749 calls it "NOT RECOMMENDED", which is why a vendor that
1517
+ * documents Basic declares {@link CLIENT_SECRET_BASIC} rather than being met with this.
1518
+ * spec-cite: RFC 6749 §2.3.1 — sending the two parameters in the body "is NOT RECOMMENDED and SHOULD be limited to
1519
+ * clients unable to directly utilize the HTTP Basic authentication scheme". Fetched 2026-11-06.
1520
+ */
1521
+ CLIENT_SECRET_POST = "client_secret_post",
1522
+ /**
1523
+ * `Authorization: Basic base64(client_id ":" client_secret)`, each half form-urlencoded BEFORE base64, and neither in
1524
+ * the body: one credential on one channel. Every authorization server must accept it (Zoom, Notion and Intuit document
1525
+ * it as their client authentication).
1526
+ * spec-cite: RFC 6749 §2.3.1 — "The client identifier is encoded using the "application/x-www-form-urlencoded"
1527
+ * encoding algorithm per Appendix B", and so is the password, before both become the Basic user-id and password; "The
1528
+ * authorization server MUST support the HTTP Basic authentication scheme". Appendix B encodes UTF-8 first, so `£` is
1529
+ * `%C2%A3` and a space is `+`. Fetched 2026-11-06.
1530
+ */
1531
+ CLIENT_SECRET_BASIC = "client_secret_basic",
1532
+ /**
1533
+ * A JWT the client signs with its own private key, sent as `client_assertion` (#3402). Performed by the
1534
+ * client-credentials grant only ({@link ProviderRestClientCredentials.privateKeyJwt}); the connected-account exchange
1535
+ * does not sign assertions, so `oauth2.tokenEndpointAuthMethod` refuses it at startup.
1536
+ * spec-cite: OpenID Connect Core 1.0 §9 — `private_key_jwt`: "Clients that have registered a public key sign a JWT
1537
+ * using that key." Fetched 2026-11-09 from https://openid.net/specs/openid-connect-core-1_0.html.
1538
+ */
1539
+ PRIVATE_KEY_JWT = "private_key_jwt"
1540
+ }
1541
+ /**
1542
+ * How the parameters of a request to a vendor's token or revocation endpoint are written in its body. See
1543
+ * {@link ProviderRestOAuth2.tokenRequestBodyEncoding} and {@link ProviderRestOAuth2.revocationRequestBodyEncoding}.
1544
+ *
1545
+ * The parameters are the same in both encodings (`grant_type`, `code`, `refresh_token`, `token`, …); only their
1546
+ * serialization and the `Content-Type` change.
1547
+ */
1548
+ export declare enum ProviderOAuth2RequestBodyEncoding {
1549
+ /**
1550
+ * `application/x-www-form-urlencoded`, which RFC 6749 and RFC 7009 specify: the default for both requests.
1551
+ * spec-cite: RFC 6749 §4.1.3 (the client makes the token request "by sending the following parameters using the
1552
+ * "application/x-www-form-urlencoded" format"; §6 does the same for a refresh), and RFC 7009 §2.1 (the revocation
1553
+ * request uses "the "application/x-www-form-urlencoded" format in the HTTP request entity-body"). Fetched 2026-11-06.
1554
+ */
1555
+ FORM = "FORM",
1556
+ /**
1557
+ * `application/json`, an object whose members are the same parameters as string values. A deviation some vendors
1558
+ * document: Notion's token endpoint takes only JSON, and Intuit's own client library revokes with a JSON body.
1559
+ * spec-cite: https://developers.notion.com/docs/authorization — the token request's `Content-Type: application/json`,
1560
+ * fetched 2026-11-06.
1561
+ */
1562
+ JSON = "JSON"
1563
+ }
1564
+ /**
1565
+ * A `scope` list encoding that deviates from RFC 6749's space-delimited list, in either direction: the token answer
1566
+ * ({@link ProviderRestOAuth2.grantedScopesDelimiter}) or the authorize request ({@link ProviderRestOAuth2.authorizeScopesDelimiter}).
1567
+ * One vocabulary for both, because it is one question (how a vendor writes a list of scopes) asked of two messages.
1568
+ */
1569
+ export declare enum ProviderOAuth2ScopeListDelimiter {
1570
+ /**
1571
+ * GitHub's token answer is `{"access_token":"gho_…","scope":"repo,gist","token_type":"bearer"}`, while its authorize
1572
+ * request takes "A space-delimited list of scopes". Slack's authorize URL takes "a comma-separated list of scopes, such
1573
+ * as: `scope=incoming-webhook,commands`".
1574
+ * spec-cite: https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps — step 2's JSON
1575
+ * response example and step 1's `scope` row, fetched 2026-10-05; https://docs.slack.dev/authentication/installing-with-oauth
1576
+ * — the authorize step's `scope` parameter, fetched 2026-10-06.
1577
+ */
1578
+ COMMA = "COMMA"
1579
+ }
1580
+ /**
1581
+ * What makes a client-authentication declaration unusable (see {@link ProviderRestOAuth2.tokenEndpointAuthMethod}):
1582
+ *
1583
+ * - a method or an encoding outside its vocabulary. The request builder tests for the declared member, so an unknown
1584
+ * value (a misspelling in a module written without types) would silently fall back to the default and send the
1585
+ * secret the way the vendor said not to;
1586
+ * - a revocation encoding with no revocation URL, a setting that changes nothing.
1587
+ */
1588
+ export declare function describeProviderOAuth2ClientAuthenticationDefects(oauth2: Pick<ProviderRestOAuth2, 'tokenEndpointAuthMethod' | 'tokenRequestBodyEncoding' | 'revocationRequestBodyEncoding' | 'rfc7009RevocationUrl'>): string[];
1589
+ /** A refresh refusal the vendor documents as a dead refresh token. See {@link ProviderRestOAuth2.refreshRefusals}. */
1590
+ export interface ProviderOAuth2RefreshRefusal {
1591
+ /** The OAuth2 `error` code of the refusal. */
1592
+ readonly error: string;
1593
+ /** The `error_description` the refusal must carry, exactly, when the code alone is not specific to a dead token. */
1594
+ readonly errorDescription?: string;
1595
+ }
1596
+ /**
1597
+ * What makes a token-request declaration unusable (follow-up to #3392), checked where the provider registry composes:
1598
+ *
1599
+ * - a {@link ProviderRestOAuth2.codeExchangeParameters} name that is not a plain identifier, that names a parameter the
1600
+ * engine writes itself, or whose value is empty;
1601
+ * - a {@link ProviderRestOAuth2.refreshRefusals} entry whose code is not code-shaped (it would never match), is
1602
+ * `invalid_grant` (already a refusal, so the entry says nothing) or `invalid_client` (the application's registration,
1603
+ * never one person's grant), or whose description is empty.
1604
+ */
1605
+ export declare function describeProviderOAuth2TokenRequestDefects(oauth2: Pick<ProviderRestOAuth2, 'codeExchangeParameters' | 'refreshRefusals'>): string[];
1606
+ /**
1607
+ * Whether a refresh's refusal is one the provider declares as a dead refresh token ({@link ProviderRestOAuth2.refreshRefusals}).
1608
+ * The one reading, shared by the refresh and its tests.
1609
+ */
1610
+ export declare function providerOAuth2RefreshRefusalIsDeclared(oauth2: Pick<ProviderRestOAuth2, 'refreshRefusals'>, answer: {
1611
+ readonly error: string;
1612
+ readonly errorDescription?: string;
1613
+ }): boolean;
1614
+ /**
1615
+ * The granted scopes a token answer's `scope` string names, read with the vendor's declared delimiter: whitespace (RFC
1616
+ * 6749 §5.1) when none is declared, a comma for {@link ProviderOAuth2ScopeListDelimiter.COMMA}.
1617
+ */
1618
+ export declare function splitProviderOAuth2GrantedScopes(scope: string, delimiter: ProviderOAuth2ScopeListDelimiter | undefined): string[];
1619
+ /**
1620
+ * The authorize request's `scope` value for the scopes asked for, written with the vendor's declared delimiter: a single
1621
+ * space (RFC 6749 §3.3) when none is declared, a comma for {@link ProviderOAuth2ScopeListDelimiter.COMMA}.
1622
+ * spec-cite: RFC 6749 §3.3 (scope is expressed as a list of space-delimited, case-sensitive strings).
1623
+ */
1624
+ export declare function joinProviderOAuth2RequestedScopes(scopes: readonly string[], delimiter: ProviderOAuth2ScopeListDelimiter | undefined): string;
1625
+ /** A vendor's refresh-token request form. See {@link ProviderRestOAuth2.offlineAccess}. */
1626
+ export interface ProviderOAuth2OfflineAccess {
1627
+ readonly form: ProviderOAuth2OfflineAccessForm;
1628
+ }
780
1629
  /** A vendor's incremental-consent behaviour. See {@link ProviderRestOAuth2.incrementalConsent}. */
781
1630
  export interface ProviderOAuth2IncrementalConsent {
782
1631
  readonly form: ProviderOAuth2IncrementalConsentForm;
@@ -798,11 +1647,121 @@ export interface ProviderOAuth2IncrementalConsent {
798
1647
  * the start of a scope, or any other `{placeholder}` in a mint scope;
799
1648
  * - two audiences admitting one host — a request host must select exactly one token.
800
1649
  */
801
- export declare function describeProviderOAuth2AudienceDefects(oauth2: Pick<ProviderRestOAuth2, 'audiences' | 'primaryAudience' | 'scopes'>): string[];
1650
+ export declare function describeProviderOAuth2AudienceDefects(oauth2: Pick<ProviderRestOAuth2, 'audiences' | 'primaryAudience' | 'scopes' | 'scopeMeaning'>): string[];
1651
+ /** Where in the token endpoint's answer a {@link ProviderOAuth2ReportedAccountFact} is read. */
1652
+ export declare enum ProviderOAuth2ReportedFactSource {
1653
+ /** The token endpoint's JSON answer itself: Slack's `team.id`, Salesforce's `instance_url`. The default. */
1654
+ TOKEN_RESPONSE = "token_response",
1655
+ /**
1656
+ * The claims of the `id_token` that answer carries (OpenID Connect): Microsoft's `tid`, the tenant the person signed
1657
+ * in to. Read without checking the token's signature, which the specification permits for an ID token received
1658
+ * directly from the token endpoint, because TLS has already authenticated who sent it. An answer carrying no
1659
+ * `id_token` reports no such fact. This is how a vendor's account identity becomes VENDOR-REPORTED when its token
1660
+ * answer names the account only inside the ID token (#2660).
1661
+ * spec-cite: OpenID Connect Core 1.0 §3.1.3.7, item 6.
1662
+ */
1663
+ ID_TOKEN_CLAIMS = "id_token_claims",
1664
+ /**
1665
+ * A query parameter of the AUTHORIZATION REDIRECT that brings the person back with the code (#3397): Intuit's
1666
+ * `realmId`, the QuickBooks company the person chose on the consent screen. `responsePath` is the parameter's name,
1667
+ * one segment. Read by the callback leg, kept with the attempt until the completion leg redeems the code, and recorded
1668
+ * only from that exchange: a refresh has no redirect, so it never restates such a fact and the stored value stands.
1669
+ *
1670
+ * The weakest of the three sources, and restricted for it. The redirect reaches this application through the
1671
+ * browser of the person who authorized, so that person could change the value before it arrives, exactly as they
1672
+ * could type an answer. Such a fact is therefore admitted only where a wrong value harms nobody but the person who
1673
+ * forged it: as a PATH value ({@link ProviderOAuth2ReportedAccountFact.pathSegmentPattern}) of a vendor that checks it
1674
+ * against the token on every call (Intuit answers a realm the token was not granted for with an authorization fault).
1675
+ * It may never be an `origin`, fill a base URL host, or route inbound deliveries, since each of those decides where a
1676
+ * credential goes or which organization receives a message; `describeProviderOAuth2ReportedFactUseDefects` refuses it.
1677
+ */
1678
+ AUTHORIZATION_REDIRECT_QUERY = "authorization_redirect_query",
1679
+ /**
1680
+ * The JSON answer of the vendor's USERINFO endpoint ({@link ProviderRestOAuth2.userInfoUrl}, #3397), fetched with the
1681
+ * access token the authorization just minted: DocuSign's `accounts[…].account_id` and `base_uri`. As trustworthy as
1682
+ * the token answer (the vendor answers over TLS, to a request the person's own token authorized), so it may be placed
1683
+ * wherever a token fact may. Read at the authorization-code exchange only: a refresh does not call the endpoint, so it
1684
+ * never restates such a fact and the stored value stands until the person connects again.
1685
+ */
1686
+ USERINFO_RESPONSE = "userinfo_response"
1687
+ }
1688
+ /** What reading a {@link ProviderOAuth2ReportedAccountFact.responsePath} out of a vendor's answer found (#3397). */
1689
+ export declare enum ProviderReportedFactReadOutcome {
1690
+ /** A non-empty string or a finite number stood at the path; `value` is its text. */
1691
+ FOUND = "FOUND",
1692
+ /** Nothing usable stood at the path: a missing key, a `null`, an object, an empty string. The fact is not reported. */
1693
+ ABSENT = "ABSENT",
1694
+ /**
1695
+ * A selection segment (`accounts[is_default=true]`) met an array in which NOT EXACTLY ONE element matched. The vendor's
1696
+ * answer does not name one element, so no fact is read from it: guessing the first would address a request to an
1697
+ * account nobody chose. `matched` is how many did.
1698
+ */
1699
+ SELECTION_NOT_SINGLE = "SELECTION_NOT_SINGLE"
1700
+ }
1701
+ /** The result of {@link readProviderReportedFactValue}. */
1702
+ export type ProviderReportedFactRead = {
1703
+ readonly outcome: ProviderReportedFactReadOutcome.FOUND;
1704
+ readonly value: string;
1705
+ } | {
1706
+ readonly outcome: ProviderReportedFactReadOutcome.ABSENT;
1707
+ } | {
1708
+ readonly outcome: ProviderReportedFactReadOutcome.SELECTION_NOT_SINGLE;
1709
+ readonly segment: string;
1710
+ readonly matched: number;
1711
+ };
1712
+ /** One step of a parsed {@link ProviderOAuth2ReportedAccountFact.responsePath}. */
1713
+ export interface ProviderReportedFactPathSegment {
1714
+ /** The own property read at this step. */
1715
+ readonly key: string;
1716
+ /** Present on a SELECTION step: the property is an array, and the one element whose `field` reads as `equals` is kept. */
1717
+ readonly select?: {
1718
+ readonly field: string;
1719
+ readonly equals: string;
1720
+ };
1721
+ }
1722
+ /**
1723
+ * The steps of a reported fact's `responsePath`, or `undefined` when it is not one (#3397). A path is dot-separated;
1724
+ * each step is an own property name, optionally followed by ONE selection `[field=value]` that picks, out of the array
1725
+ * at that property, the single element whose `field` reads as `value`: `accounts[is_default=true].account_id`.
1726
+ *
1727
+ * Names, fields and values may not contain `.`, `[`, `]` or `=`; a value may be empty. Kept this small on purpose: it
1728
+ * addresses one element by one stated condition, which is what a vendor documenting "the default account" means, and
1729
+ * nothing that would need a query language.
1730
+ */
1731
+ export declare function parseProviderReportedFactPath(path: string): readonly ProviderReportedFactPathSegment[] | undefined;
1732
+ /**
1733
+ * The value at a reported fact's `responsePath` inside a vendor's JSON answer (#3397): a token answer, the claims of
1734
+ * its ID token, or a userinfo answer. Own properties only (the answer is a vendor's JSON, and `constructor` is not a
1735
+ * fact). A FOUND value is a non-empty string or a finite number's decimal text.
1736
+ *
1737
+ * A selection step keeps the ONE array element whose field reads as the stated value (a string as itself, a number as
1738
+ * its decimal text, a boolean as `true` / `false`, so DocuSign's `is_default: true` matches `[is_default=true]` whether
1739
+ * it is sent as a boolean or a string). Zero or several matches is {@link ProviderReportedFactReadOutcome.SELECTION_NOT_SINGLE}:
1740
+ * two facts selected with the same condition (`accounts[is_default=true].account_id` and `….base_uri`) are therefore
1741
+ * read from the same element or not at all. Anything else that does not lead to a scalar (a missing key, a property
1742
+ * that is not an array where a selection is written, an unparsable path) is ABSENT.
1743
+ */
1744
+ export declare function readProviderReportedFactValue(payload: unknown, path: string): ProviderReportedFactRead;
1745
+ /**
1746
+ * The query parameters an authorization redirect carries for the OAuth protocol itself, never as an account fact: a
1747
+ * redirect-sourced fact named like one would read the code, the state or the error as the account.
1748
+ * spec-cite: RFC 6749 §4.1.2 (`code`, `state`) and §4.1.2.1 (`error`, `error_description`, `error_uri`); RFC 9207 §2
1749
+ * (`iss`).
1750
+ * semantic-literal-boundary: the OAuth protocol's own redirect parameter names, compared with a module's declaration.
1751
+ */
1752
+ export declare const PROVIDER_OAUTH2_REDIRECT_PROTOCOL_PARAMETERS: readonly string[];
802
1753
  /** One vendor-reported account fact. See {@link ProviderRestOAuth2.reportedAccountFacts}. */
803
1754
  export interface ProviderOAuth2ReportedAccountFact {
804
- /** Dot-path inside the token endpoint's JSON answer. A string or finite number there is the value. */
1755
+ /**
1756
+ * Dot-path inside the fact's {@link source}: the token endpoint's JSON answer by default, the claims of its
1757
+ * `id_token`, or the userinfo endpoint's JSON answer. A string or finite number there is the value. A step may select
1758
+ * ONE element of an array by a stated condition, `accounts[is_default=true].account_id` (#3397); zero or several
1759
+ * matching elements report nothing and refuse the connect ({@link readProviderReportedFactValue}). For
1760
+ * {@link ProviderOAuth2ReportedFactSource.AUTHORIZATION_REDIRECT_QUERY}, the redirect's query parameter name.
1761
+ */
805
1762
  readonly responsePath: string;
1763
+ /** Where {@link responsePath} is read. Omitted, the token endpoint's JSON answer. */
1764
+ readonly source?: ProviderOAuth2ReportedFactSource;
806
1765
  /**
807
1766
  * Present when the value is an https ORIGIN operations dial. The same DECLARED_VALUES vocabulary an
808
1767
  * ORIGIN placeholder uses: exact origins, or `https://<dns-labels><suffix>` for each dotted suffix.
@@ -810,7 +1769,131 @@ export interface ProviderOAuth2ReportedAccountFact {
810
1769
  readonly origin?: Extract<ProviderOAuth2EndpointHostAllowance, {
811
1770
  readonly kind: ProviderOAuth2EndpointHostAllowanceKind.DECLARED_VALUES;
812
1771
  }>;
1772
+ /**
1773
+ * Present when operations may place the value as ONE PATH SEGMENT (#3397): QuickBooks' `/v3/company/{realmId}/…`. An
1774
+ * operation names the fact on a PATH parameter ({@link ProviderRestOperationParameter.connectionFact}) and the caller
1775
+ * never supplies it. A JavaScript regular expression the WHOLE value must match (it is anchored for you), checked when
1776
+ * the connection is made (a value that does not match, or no value, refuses the connect) and again on every call, as
1777
+ * an origin is. A value that matches is still refused when it is `.` or `..` or holds a `/`, so it can never move the
1778
+ * request to another path. Keep it as narrow as the vendor documents: `\d+` for a QuickBooks company id.
1779
+ *
1780
+ * Without this a vendor-reported fact fills nothing: what the vendor reported is not an answer the person gave, and
1781
+ * only a declared shape keeps a value that would otherwise go unexamined out of a URL.
1782
+ */
1783
+ readonly pathSegmentPattern?: string;
1784
+ /**
1785
+ * `true` when the value may fill the base URL's `{<this fact's name>}` HOST placeholder (#3397), admitted against the
1786
+ * REST contract's `baseUrlHostAllowances` entry for that name on every call: the same allowance, and the same
1787
+ * resolver, that admit a host a person typed at connect. Needs a `DECLARED_VALUES` allowance under the fact's name.
1788
+ * Never filled into an OAuth2 endpoint (authorize, token, revocation): those carry the client secret, and only the
1789
+ * person's answers or the deployment fill them. An `origin` is the other way to address the account; a fact is one
1790
+ * or the other.
1791
+ */
1792
+ readonly fillsBaseUrlHost?: true;
1793
+ /**
1794
+ * `true` when the inbound receiver routes the vendor's deliveries to an organization by this fact: Slack's
1795
+ * `team.id`, the workspace an event comes from (#2660). Such a fact may name ONE organization only, so an
1796
+ * organization's connection reporting a value another organization's enabled connection already reports is
1797
+ * refused at connect, naming why. Routing fails closed on a value two organizations hold either way; the refusal is
1798
+ * what makes that a clear answer at connect instead of deliveries that silently route nowhere.
1799
+ */
1800
+ readonly routesInboundDeliveries?: true;
813
1801
  }
1802
+ /** What a {@link ProviderOAuth2IdTokenRequirement} asks of the sign-in's ID token claims. */
1803
+ export declare enum ProviderOAuth2IdTokenRequirementKind {
1804
+ /**
1805
+ * The claim is an array holding at least one of `values`, compared exactly. Microsoft's `wids`, the directory roles
1806
+ * the person holds: a tenant claim requires a role that administers the tenant.
1807
+ */
1808
+ CLAIM_CONTAINS_ANY = "claim_contains_any",
1809
+ /**
1810
+ * When the claim is present, it equals `equalsClaim`. Microsoft's `idp` against `iss`: they differ for a guest, an
1811
+ * account another tenant authenticated, who speaks for nothing in this one.
1812
+ */
1813
+ CLAIM_EQUALS_CLAIM_WHEN_PRESENT = "claim_equals_claim_when_present"
1814
+ }
1815
+ /**
1816
+ * One condition the ID token of the sign-in that MAKES a connection must meet, or the connect is refused before
1817
+ * anything is stored (#2663). For a connection whose reported fact routes deliveries (a Microsoft tenant), proving
1818
+ * the account is not enough: the person must also have the authority to bind it to an organization, and the vendor's
1819
+ * signed claims are where that authority is stated.
1820
+ *
1821
+ * Checked at the authorization-code exchange only. A refresh does not re-make the connection, and a vendor need not
1822
+ * return an ID token with it; a person whose authority lapsed is caught the next time the connection is made.
1823
+ */
1824
+ export type ProviderOAuth2IdTokenRequirement = {
1825
+ readonly kind: ProviderOAuth2IdTokenRequirementKind.CLAIM_CONTAINS_ANY;
1826
+ readonly claim: string;
1827
+ readonly values: readonly string[];
1828
+ } | {
1829
+ readonly kind: ProviderOAuth2IdTokenRequirementKind.CLAIM_EQUALS_CLAIM_WHEN_PRESENT;
1830
+ readonly claim: string;
1831
+ readonly equalsClaim: string;
1832
+ };
1833
+ /** Why an ID token's claims may not be used (#2663 re-review I1). See {@link providerOAuth2IdTokenRejection}. */
1834
+ export declare enum ProviderOAuth2IdTokenRejection {
1835
+ /** The token endpoint's answer carries no ID token, or not one whose payload is a JSON object. */
1836
+ ABSENT = "absent",
1837
+ /** `iss` is not the declared issuer, with its placeholders filled from the token's claims. */
1838
+ ISSUER_MISMATCH = "issuer_mismatch",
1839
+ /** `aud` does not name this client, or names another audience beside it. */
1840
+ AUDIENCE_MISMATCH = "audience_mismatch",
1841
+ /** `exp` is missing, or not after the current time. */
1842
+ EXPIRED = "expired"
1843
+ }
1844
+ /**
1845
+ * Why these ID token claims may not be used, or `undefined` when they may: the token names the declared issuer, this
1846
+ * client as its only audience, and an expiry still ahead. See {@link ProviderRestOAuth2.idTokenIssuer}.
1847
+ *
1848
+ * A placeholder of the issuer naming a claim the token does not carry as a non-empty string fails the issuer check:
1849
+ * an issuer that cannot be written cannot be matched.
1850
+ */
1851
+ export declare function providerOAuth2IdTokenRejection(claims: Readonly<Record<string, unknown>> | undefined, expected: {
1852
+ readonly issuer: string;
1853
+ readonly clientId: string;
1854
+ readonly nowEpochSeconds: number;
1855
+ }): ProviderOAuth2IdTokenRejection | undefined;
1856
+ /** Whether ID token claims meet one requirement. An absent ID token meets none. */
1857
+ export declare function providerOAuth2IdTokenRequirementHolds(requirement: ProviderOAuth2IdTokenRequirement, claims: Readonly<Record<string, unknown>> | undefined): boolean;
1858
+ /**
1859
+ * What makes a declaration of ID token requirements unusable: a requirement with no claim or no value, and any
1860
+ * requirement on a contract that does not ask for `openid`, without which "the behavior is entirely unspecified" and
1861
+ * no ID token is returned to read.
1862
+ * spec-cite: OpenID Connect Core 1.0 §3.1.2.1 — the `scope` parameter row ("If the openid scope value is not present,
1863
+ * the behavior is entirely unspecified").
1864
+ */
1865
+ export declare function describeProviderOAuth2IdTokenRequirementDefects(oauth2: Pick<ProviderRestOAuth2, 'idTokenRequirements' | 'scopes' | 'reportedAccountFacts' | 'idTokenIssuer'>): string[];
1866
+ /**
1867
+ * Whether a vendor-reported value may stand as one path segment under its fact's declared
1868
+ * {@link ProviderOAuth2ReportedAccountFact.pathSegmentPattern} (#3397): the WHOLE value matches the pattern, and it is
1869
+ * not empty, not a dot-segment and holds no `/`, whatever the pattern admits. The one admission, applied where the value
1870
+ * is captured (the authorization) and where it is spent (every call). A pattern that does not compile admits nothing.
1871
+ */
1872
+ export declare function providerReportedPathSegmentAdmits(pattern: string, value: string): boolean;
1873
+ /** The REST-contract slice {@link describeProviderOAuth2ReportedFactUseDefects} reads. */
1874
+ export interface ProviderReportedFactUseContract {
1875
+ readonly baseUrl?: string;
1876
+ readonly baseUrlConnectionFact?: string;
1877
+ readonly baseUrlHostAllowances?: Readonly<Record<string, ProviderOAuth2EndpointHostAllowance>>;
1878
+ readonly oauth2?: Pick<ProviderRestOAuth2, 'reportedAccountFacts' | 'connectionParameters'> & Partial<Pick<ProviderRestOAuth2, 'tokenUrl' | 'userInfoUrl'>>;
1879
+ }
1880
+ /**
1881
+ * What makes the declared USES of a connection's vendor-reported facts unsafe or unusable (#3397), checked at boot with
1882
+ * the contract's other declarations:
1883
+ *
1884
+ * - a fact read from the authorization redirect is something the person who authorized could change, so it may not be
1885
+ * an `origin`, fill a base URL host, or route inbound deliveries, and its name must be one query parameter that is
1886
+ * not the OAuth protocol's own (`code`, `state`, …);
1887
+ * - a `pathSegmentPattern` must compile, admit no empty value, and not sit beside an `origin`;
1888
+ * - a `fillsBaseUrlHost` fact must name a `{placeholder}` of the base URL that a `DECLARED_VALUES` allowance governs,
1889
+ * must not also be an `origin` or something the person is asked at connect, and cannot share a contract with
1890
+ * `baseUrlConnectionFact`, which already decides where calls go;
1891
+ * - every other `responsePath` must parse ({@link parseProviderReportedFactPath});
1892
+ * - a fact read from the userinfo answer needs a `userInfoUrl`, a `userInfoUrl` needs a fact that reads it (a request
1893
+ * carrying the person's token that nothing uses is not made), and the userinfo endpoint may carry only the
1894
+ * host-forming placeholders the token endpoint carries, in the same position (it is the same authorization server).
1895
+ */
1896
+ export declare function describeProviderOAuth2ReportedFactUseDefects(contract: ProviderReportedFactUseContract): string[];
814
1897
  /** The values a whole-scope placeholder admits. See {@link ProviderRestOAuth2.scopeValueAllowances}. */
815
1898
  export interface ProviderOAuth2ScopeValueAllowance {
816
1899
  readonly values: readonly string[];
@@ -980,6 +2063,24 @@ export type ProviderOAuth2EndpointHostAllowance = {
980
2063
  * so `evilmy.salesforce.com` never matches `.my.salesforce.com`.
981
2064
  */
982
2065
  readonly hostSuffixes?: readonly string[];
2066
+ /**
2067
+ * The MOST DNS labels an admitted host may carry before its suffix (#3640); absent, any number. Applies to every
2068
+ * entry of `hostSuffixes`, and only to them (an exact `values` entry is admitted as written).
2069
+ *
2070
+ * Declared only where the VENDOR documents the shape. Shopify does: a store host is exactly one label under
2071
+ * `.myshopify.com` ("Confirm the `shop` parameter matches `^[a-zA-Z0-9][a-zA-Z0-9\-]*\.myshopify\.com$`"), so it
2072
+ * declares `1`. Without the bound, a person answering `shop` with the full domain they see, `acme.myshopify.com`,
2073
+ * composed `acme.myshopify.com.myshopify.com`: a host under the suffix that does not exist, which failed every
2074
+ * request on DNS. (That answer is now also stripped to its handle, see `stripProviderHostAnswerTemplateSuffix`; the
2075
+ * bound is what refuses `acme.evil.myshopify.com`, naming the expected form.)
2076
+ * spec-cite: https://shopify.dev/docs/apps/build/authentication-authorization/access-tokens/authorization-code-grant —
2077
+ * the `shop` parameter check, as quoted in the Shopify module's header (fetched 2026-11-10).
2078
+ *
2079
+ * Every place a suffix admits a host reads it, through `providerHostIsUnderSuffix`: the answer filled into an endpoint
2080
+ * or base URL, the token-endpoint host description, the declined-value check. A positive integer, with at least one
2081
+ * suffix (`describeProviderOAuth2EndpointHostAllowanceDefects`).
2082
+ */
2083
+ readonly hostSuffixMaxLabels?: number;
983
2084
  /**
984
2085
  * ORIGIN only: an admitted value must ALSO have the same origin as the deployment's configured base
985
2086
  * URL (the REST contract's `baseUrl` / `baseUrlEnvVarName`) (#991 review F4).
@@ -1085,6 +2186,59 @@ export declare enum ProviderOAuth2EndpointTemplateDefect {
1085
2186
  * hyphen; 63 octets per label).
1086
2187
  */
1087
2188
  export declare const PROVIDER_OAUTH2_DNS_NAME_PATTERN: RegExp;
2189
+ /**
2190
+ * Whether `host` is `<labels><suffix>`: it ends with the dotted `suffix`, what precedes the suffix is a DNS name (never
2191
+ * empty, so the bare suffix is not admitted), and that DNS name carries at most `maxLabels` labels (#3640).
2192
+ *
2193
+ * THE one suffix test. Every place a declared host suffix admits a host — an answer filled into an endpoint or a base URL,
2194
+ * an audience selecting a request host, the token-endpoint host description, a declined value a suffix would still admit —
2195
+ * asks this function, so a label bound declared once holds at all of them. `maxLabels` absent means unbounded, which is
2196
+ * what every suffix meant before the bound existed. A bound that is not a positive integer admits nothing (fail closed):
2197
+ * the declaration checks refuse it where a person is reading a diff, and this keeps the runtime closed regardless.
2198
+ *
2199
+ * Case-insensitive; the caller need not lower-case.
2200
+ */
2201
+ export declare function providerHostIsUnderSuffix(host: string, suffix: string, maxLabels?: number): boolean;
2202
+ /** One declared host suffix with its label bound, as {@link providerHostSuffixesOverlap} compares them. */
2203
+ export interface ProviderHostSuffixBound {
2204
+ readonly suffix: string;
2205
+ /** At most this many DNS labels before the suffix; absent, unbounded. See {@link providerHostIsUnderSuffix}. */
2206
+ readonly maxLabels?: number;
2207
+ }
2208
+ /**
2209
+ * Whether some host is admitted under BOTH suffixes (#3640). Two suffixes can only share a host when one ends with the
2210
+ * other (`.a.b` and `.b`): a host under the longer one carries the extra labels (`.a`) before the shorter one, so the
2211
+ * shorter one's bound must leave room for one label of its own plus those. Equal suffixes always share a host.
2212
+ */
2213
+ export declare function providerHostSuffixesOverlap(left: ProviderHostSuffixBound, right: ProviderHostSuffixBound): boolean;
2214
+ /**
2215
+ * The bare answer for a placeholder that OPENS a host, when the person typed the whole host (#3640).
2216
+ *
2217
+ * `https://{shop}.myshopify.com` asks for the store's handle, and the person connecting sees `acme.myshopify.com` in the
2218
+ * vendor's own screens. Filled verbatim, that answer dials `acme.myshopify.com.myshopify.com`: a host the suffix admits
2219
+ * (it ends in `.myshopify.com`) that does not exist, so every request fails on DNS naming a host rather than the answer.
2220
+ * The literal text the template writes after the placeholder (`literalHostSuffix`) is therefore stripped ONCE from an
2221
+ * answer that ends with it: `acme.myshopify.com` → `acme`. Nothing else is rewritten; the result is then admitted like
2222
+ * any other answer, so an answer with too many labels left (`acme.evil.myshopify.com` → `acme.evil` under a one-label
2223
+ * bound) is still refused.
2224
+ *
2225
+ * Generic rather than per vendor, because it is a property of the TEMPLATE: every provider whose host opens with a
2226
+ * placeholder (Shopify, Zendesk) asks for the part before a literal the vendor shows people with it attached. Done where
2227
+ * the template is filled, not in a connect prompt, so the OAuth start, the stored-answer re-admission and every
2228
+ * operation's base URL read the same answer the same way, whichever screen or flag supplied it. A host that literally
2229
+ * repeated its suffix is never a real vendor host, so nothing a person could mean is lost.
2230
+ */
2231
+ export declare function stripProviderHostAnswerTemplateSuffix(value: string, literalHostSuffix: string | undefined): string;
2232
+ /**
2233
+ * The words a refusal uses for the answer a bounded suffix expects (#3640): `a single DNS label before .myshopify.com
2234
+ * (the 'acme' of acme.myshopify.com)`. Shared so every refusal names the same form.
2235
+ */
2236
+ export declare function describeProviderHostSuffixExpectedForm(suffix: string, maxLabels: number | undefined, answerExcludesSuffix: boolean): string;
2237
+ /**
2238
+ * Why a declared label bound on host suffixes cannot be honoured (#3640): it is not a positive integer, or there is no
2239
+ * suffix for it to bound. Shared by the endpoint allowances and the audiences, so both refuse the same shapes.
2240
+ */
2241
+ export declare function describeProviderHostSuffixMaxLabelsDefects(maxLabels: number | undefined, hostSuffixes: readonly string[] | undefined): string[];
1088
2242
  /**
1089
2243
  * Why a DECLARED host allowance cannot be applied where its placeholder sits — the position rules the
1090
2244
  * transposer enforces at GENERATION time, so a broken declaration refuses the batch instead of being