@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.
- package/dist/esm/companion-exports.js.map +1 -1
- package/dist/esm/core/commons.external-connectors-models.schemas.d.ts +140 -0
- package/dist/esm/core/commons.external-connectors-models.schemas.d.ts.map +1 -1
- package/dist/esm/core/commons.external-connectors-models.schemas.js +203 -0
- package/dist/esm/core/commons.external-connectors-models.schemas.js.map +1 -1
- package/dist/esm/core/oauth2.enums.d.ts.map +1 -1
- package/dist/esm/core/oauth2.enums.js.map +1 -1
- package/dist/esm/core/operation-classification.external-connectors-models.schemas.d.ts.map +1 -1
- package/dist/esm/core/operation-classification.external-connectors-models.schemas.js.map +1 -1
- package/dist/esm/core/operations.external-connectors-models.schemas.js.map +1 -1
- package/dist/esm/core/security.external-connectors-models.schemas.d.ts +4 -2
- package/dist/esm/core/security.external-connectors-models.schemas.d.ts.map +1 -1
- package/dist/esm/core/security.external-connectors-models.schemas.js +10 -4
- package/dist/esm/core/security.external-connectors-models.schemas.js.map +1 -1
- package/dist/esm/index.d.ts +8 -0
- package/dist/esm/index.d.ts.map +1 -1
- package/dist/esm/index.js +8 -0
- package/dist/esm/index.js.map +1 -1
- package/dist/esm/protocols/agent-client-protocol.external-connectors-models.schemas.d.ts +9 -42
- package/dist/esm/protocols/agent-client-protocol.external-connectors-models.schemas.d.ts.map +1 -1
- package/dist/esm/protocols/agent-client-protocol.external-connectors-models.schemas.js +31 -1
- package/dist/esm/protocols/agent-client-protocol.external-connectors-models.schemas.js.map +1 -1
- package/dist/esm/protocols/billing.standard-interface.schemas.d.ts +64 -3
- package/dist/esm/protocols/billing.standard-interface.schemas.d.ts.map +1 -1
- package/dist/esm/protocols/billing.standard-interface.schemas.js +23 -2
- package/dist/esm/protocols/billing.standard-interface.schemas.js.map +1 -1
- package/dist/esm/protocols/content-safety.external-connectors-models.schemas.d.ts +150 -0
- package/dist/esm/protocols/content-safety.external-connectors-models.schemas.d.ts.map +1 -0
- package/dist/esm/protocols/content-safety.external-connectors-models.schemas.js +182 -0
- package/dist/esm/protocols/content-safety.external-connectors-models.schemas.js.map +1 -0
- package/dist/esm/protocols/document-extraction.external-connectors-models.schemas.d.ts +41 -9
- package/dist/esm/protocols/document-extraction.external-connectors-models.schemas.d.ts.map +1 -1
- package/dist/esm/protocols/document-extraction.external-connectors-models.schemas.js +40 -14
- package/dist/esm/protocols/document-extraction.external-connectors-models.schemas.js.map +1 -1
- package/dist/esm/protocols/electronic-signature.external-connectors-models.schemas.d.ts +157 -0
- package/dist/esm/protocols/electronic-signature.external-connectors-models.schemas.d.ts.map +1 -0
- package/dist/esm/protocols/electronic-signature.external-connectors-models.schemas.js +134 -0
- package/dist/esm/protocols/electronic-signature.external-connectors-models.schemas.js.map +1 -0
- package/dist/esm/protocols/email-inbound.standard-interface.schemas.d.ts +85 -0
- package/dist/esm/protocols/email-inbound.standard-interface.schemas.d.ts.map +1 -1
- package/dist/esm/protocols/email-inbound.standard-interface.schemas.js +46 -2
- package/dist/esm/protocols/email-inbound.standard-interface.schemas.js.map +1 -1
- package/dist/esm/protocols/email.external-connectors-models.schemas.js.map +1 -1
- package/dist/esm/protocols/email.standard-interface.schemas.d.ts.map +1 -1
- package/dist/esm/protocols/email.standard-interface.schemas.js +4 -0
- package/dist/esm/protocols/email.standard-interface.schemas.js.map +1 -1
- package/dist/esm/protocols/embeddings.external-connectors-models.schemas.d.ts +86 -10
- package/dist/esm/protocols/embeddings.external-connectors-models.schemas.d.ts.map +1 -1
- package/dist/esm/protocols/embeddings.external-connectors-models.schemas.js +146 -7
- package/dist/esm/protocols/embeddings.external-connectors-models.schemas.js.map +1 -1
- package/dist/esm/protocols/file-storage.standard-interface.d.ts +14 -1
- package/dist/esm/protocols/file-storage.standard-interface.d.ts.map +1 -1
- package/dist/esm/protocols/file-storage.standard-interface.js +6 -0
- package/dist/esm/protocols/file-storage.standard-interface.js.map +1 -1
- package/dist/esm/protocols/frontend.external-connectors-models.schemas.js.map +1 -1
- package/dist/esm/protocols/graphql-operations.external-connectors-models.schemas.d.ts +254 -0
- package/dist/esm/protocols/graphql-operations.external-connectors-models.schemas.d.ts.map +1 -0
- package/dist/esm/protocols/graphql-operations.external-connectors-models.schemas.js +480 -0
- package/dist/esm/protocols/graphql-operations.external-connectors-models.schemas.js.map +1 -0
- package/dist/esm/protocols/hooks-capability.external-connectors-models.schemas.d.ts +7 -2
- package/dist/esm/protocols/hooks-capability.external-connectors-models.schemas.d.ts.map +1 -1
- package/dist/esm/protocols/hooks-capability.external-connectors-models.schemas.js.map +1 -1
- package/dist/esm/protocols/hooks.external-connectors-models.schemas.d.ts +482 -7
- package/dist/esm/protocols/hooks.external-connectors-models.schemas.d.ts.map +1 -1
- package/dist/esm/protocols/hooks.external-connectors-models.schemas.js +348 -0
- package/dist/esm/protocols/hooks.external-connectors-models.schemas.js.map +1 -1
- package/dist/esm/protocols/image.external-connectors-models.schemas.js.map +1 -1
- package/dist/esm/protocols/llm.external-connectors-models.schemas.d.ts +165 -8
- package/dist/esm/protocols/llm.external-connectors-models.schemas.d.ts.map +1 -1
- package/dist/esm/protocols/llm.external-connectors-models.schemas.js +243 -20
- package/dist/esm/protocols/llm.external-connectors-models.schemas.js.map +1 -1
- package/dist/esm/protocols/oauth2-provider-assurance.definitions.js.map +1 -1
- package/dist/esm/protocols/oauth2-provider-assurance.schemas.js.map +1 -1
- package/dist/esm/protocols/oauth2.external-connectors-models.schemas.js.map +1 -1
- package/dist/esm/protocols/provider-configuration-authoring.external-connectors-models.schemas.d.ts +52 -0
- package/dist/esm/protocols/provider-configuration-authoring.external-connectors-models.schemas.d.ts.map +1 -0
- package/dist/esm/protocols/provider-configuration-authoring.external-connectors-models.schemas.js +132 -0
- package/dist/esm/protocols/provider-configuration-authoring.external-connectors-models.schemas.js.map +1 -0
- package/dist/esm/protocols/provider-connection-parameters.external-connectors-models.d.ts +111 -0
- package/dist/esm/protocols/provider-connection-parameters.external-connectors-models.d.ts.map +1 -0
- package/dist/esm/protocols/provider-connection-parameters.external-connectors-models.js +203 -0
- package/dist/esm/protocols/provider-connection-parameters.external-connectors-models.js.map +1 -0
- package/dist/esm/protocols/provider-oauth2-token-endpoint-hosts.external-connectors-models.d.ts +6 -0
- package/dist/esm/protocols/provider-oauth2-token-endpoint-hosts.external-connectors-models.d.ts.map +1 -1
- package/dist/esm/protocols/provider-oauth2-token-endpoint-hosts.external-connectors-models.js +13 -7
- package/dist/esm/protocols/provider-oauth2-token-endpoint-hosts.external-connectors-models.js.map +1 -1
- package/dist/esm/protocols/provider-vendor-registration.external-connectors-models.d.ts +50 -0
- package/dist/esm/protocols/provider-vendor-registration.external-connectors-models.d.ts.map +1 -0
- package/dist/esm/protocols/provider-vendor-registration.external-connectors-models.js +30 -0
- package/dist/esm/protocols/provider-vendor-registration.external-connectors-models.js.map +1 -0
- package/dist/esm/protocols/rest-operations.external-connectors-models.schemas.d.ts +1165 -11
- package/dist/esm/protocols/rest-operations.external-connectors-models.schemas.d.ts.map +1 -1
- package/dist/esm/protocols/rest-operations.external-connectors-models.schemas.js +1217 -9
- package/dist/esm/protocols/rest-operations.external-connectors-models.schemas.js.map +1 -1
- package/dist/esm/protocols/service-account-token.external-connectors-models.schemas.d.ts +73 -0
- package/dist/esm/protocols/service-account-token.external-connectors-models.schemas.d.ts.map +1 -0
- package/dist/esm/protocols/service-account-token.external-connectors-models.schemas.js +82 -0
- package/dist/esm/protocols/service-account-token.external-connectors-models.schemas.js.map +1 -0
- package/dist/esm/protocols/sms.external-connectors-models.schemas.js.map +1 -1
- package/dist/esm/protocols/sms.standard-interface.schemas.d.ts +79 -1
- package/dist/esm/protocols/sms.standard-interface.schemas.d.ts.map +1 -1
- package/dist/esm/protocols/sms.standard-interface.schemas.js +93 -0
- package/dist/esm/protocols/sms.standard-interface.schemas.js.map +1 -1
- package/dist/esm/protocols/subject-erasure-effect.standard-interface.d.ts +133 -0
- package/dist/esm/protocols/subject-erasure-effect.standard-interface.d.ts.map +1 -0
- package/dist/esm/protocols/subject-erasure-effect.standard-interface.js +61 -0
- package/dist/esm/protocols/subject-erasure-effect.standard-interface.js.map +1 -0
- package/dist/tsconfig.build.tsbuildinfo +1 -1
- package/package.json +5 -5
- 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
|
|
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
|
|
282
|
-
*
|
|
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
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|