@yadsh/dsh-qa-integrations 0.6.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (183) hide show
  1. package/README.md +341 -303
  2. package/lib/broker.js +12 -0
  3. package/lib/broker.js.map +1 -1
  4. package/lib/client/bitrix24.js +66 -5
  5. package/lib/client/bitrix24.js.map +1 -1
  6. package/lib/client/confluence.js +117 -128
  7. package/lib/client/confluence.js.map +1 -1
  8. package/lib/client/gitlab.js +1 -1
  9. package/lib/client/gitlab.js.map +1 -1
  10. package/lib/client/index.js +25 -5
  11. package/lib/client/index.js.map +1 -1
  12. package/lib/client/integrations.js +1 -1
  13. package/lib/client/integrations.js.map +1 -1
  14. package/lib/client/jira.js +115 -126
  15. package/lib/client/jira.js.map +1 -1
  16. package/lib/client/operator-card.js +537 -0
  17. package/lib/client/operator-card.js.map +1 -0
  18. package/lib/client/operator-controls.js +232 -0
  19. package/lib/client/operator-controls.js.map +1 -0
  20. package/lib/client/styles.js +60 -0
  21. package/lib/client/styles.js.map +1 -1
  22. package/lib/client/testit.js +39 -3
  23. package/lib/client/testit.js.map +1 -1
  24. package/lib/client/weblate.js +38 -3
  25. package/lib/client/weblate.js.map +1 -1
  26. package/lib/client.js +2966 -871
  27. package/lib/client.js.map +1 -1
  28. package/lib/coerce.js +17 -1
  29. package/lib/coerce.js.map +1 -1
  30. package/lib/config.js.map +1 -1
  31. package/lib/errors.js +22 -0
  32. package/lib/errors.js.map +1 -1
  33. package/lib/index.js +211 -52
  34. package/lib/index.js.map +1 -1
  35. package/lib/providers/bitrix24/catalog.js +138 -8
  36. package/lib/providers/bitrix24/catalog.js.map +1 -1
  37. package/lib/providers/bitrix24/config.js +84 -14
  38. package/lib/providers/bitrix24/config.js.map +1 -1
  39. package/lib/providers/bitrix24/index.js +100 -0
  40. package/lib/providers/bitrix24/index.js.map +1 -1
  41. package/lib/providers/bitrix24/operations.js +5 -9
  42. package/lib/providers/bitrix24/operations.js.map +1 -1
  43. package/lib/providers/bitrix24/transport.js +11 -31
  44. package/lib/providers/bitrix24/transport.js.map +1 -1
  45. package/lib/providers/confluence/adf.js +28 -23
  46. package/lib/providers/confluence/adf.js.map +1 -1
  47. package/lib/providers/confluence/catalog.js +91 -7
  48. package/lib/providers/confluence/catalog.js.map +1 -1
  49. package/lib/providers/confluence/config.js +27 -2
  50. package/lib/providers/confluence/config.js.map +1 -1
  51. package/lib/providers/confluence/credential-help.js +14 -8
  52. package/lib/providers/confluence/credential-help.js.map +1 -1
  53. package/lib/providers/confluence/dialect.js +215 -0
  54. package/lib/providers/confluence/dialect.js.map +1 -0
  55. package/lib/providers/confluence/index.js +393 -79
  56. package/lib/providers/confluence/index.js.map +1 -1
  57. package/lib/providers/confluence/operations.js +208 -153
  58. package/lib/providers/confluence/operations.js.map +1 -1
  59. package/lib/providers/confluence/storage.js +690 -0
  60. package/lib/providers/confluence/storage.js.map +1 -0
  61. package/lib/providers/confluence/transport.js +26 -89
  62. package/lib/providers/confluence/transport.js.map +1 -1
  63. package/lib/providers/gitlab/config.js +2 -3
  64. package/lib/providers/gitlab/config.js.map +1 -1
  65. package/lib/providers/gitlab/index.js +2 -20
  66. package/lib/providers/gitlab/index.js.map +1 -1
  67. package/lib/providers/gitlab/operations.js +7 -45
  68. package/lib/providers/gitlab/operations.js.map +1 -1
  69. package/lib/providers/gitlab/transport.js +2 -18
  70. package/lib/providers/gitlab/transport.js.map +1 -1
  71. package/lib/providers/jira/adf.js +19 -14
  72. package/lib/providers/jira/adf.js.map +1 -1
  73. package/lib/providers/jira/catalog.js +125 -4
  74. package/lib/providers/jira/catalog.js.map +1 -1
  75. package/lib/providers/jira/config.js +27 -2
  76. package/lib/providers/jira/config.js.map +1 -1
  77. package/lib/providers/jira/credential-help.js +16 -7
  78. package/lib/providers/jira/credential-help.js.map +1 -1
  79. package/lib/providers/jira/dialect.js +94 -0
  80. package/lib/providers/jira/dialect.js.map +1 -0
  81. package/lib/providers/jira/index.js +327 -67
  82. package/lib/providers/jira/index.js.map +1 -1
  83. package/lib/providers/jira/jql.js +54 -21
  84. package/lib/providers/jira/jql.js.map +1 -1
  85. package/lib/providers/jira/operations.js +77 -55
  86. package/lib/providers/jira/operations.js.map +1 -1
  87. package/lib/providers/jira/tools.js +1 -1
  88. package/lib/providers/jira/tools.js.map +1 -1
  89. package/lib/providers/jira/transport.js +12 -83
  90. package/lib/providers/jira/transport.js.map +1 -1
  91. package/lib/providers/shared/health.js +31 -0
  92. package/lib/providers/shared/health.js.map +1 -0
  93. package/lib/providers/shared/http.js +20 -0
  94. package/lib/providers/shared/http.js.map +1 -1
  95. package/lib/providers/shared/paths.js +14 -0
  96. package/lib/providers/shared/paths.js.map +1 -0
  97. package/lib/providers/shared/payload.js +46 -0
  98. package/lib/providers/shared/payload.js.map +1 -0
  99. package/lib/providers/teamcity/artifacts.js +0 -8
  100. package/lib/providers/teamcity/artifacts.js.map +1 -1
  101. package/lib/providers/teamcity/config.js +2 -3
  102. package/lib/providers/teamcity/config.js.map +1 -1
  103. package/lib/providers/teamcity/index.js +2 -20
  104. package/lib/providers/teamcity/index.js.map +1 -1
  105. package/lib/providers/teamcity/operations.js +5 -39
  106. package/lib/providers/teamcity/operations.js.map +1 -1
  107. package/lib/providers/teamcity/transport.js +2 -11
  108. package/lib/providers/teamcity/transport.js.map +1 -1
  109. package/lib/providers/testit/catalog.js +77 -0
  110. package/lib/providers/testit/catalog.js.map +1 -1
  111. package/lib/providers/testit/config.js +2 -3
  112. package/lib/providers/testit/config.js.map +1 -1
  113. package/lib/providers/testit/index.js +260 -4
  114. package/lib/providers/testit/index.js.map +1 -1
  115. package/lib/providers/testit/operations.js +34 -63
  116. package/lib/providers/testit/operations.js.map +1 -1
  117. package/lib/providers/testit/transport.js +2 -18
  118. package/lib/providers/testit/transport.js.map +1 -1
  119. package/lib/providers/weblate/catalog.js +103 -9
  120. package/lib/providers/weblate/catalog.js.map +1 -1
  121. package/lib/providers/weblate/config.js +2 -3
  122. package/lib/providers/weblate/config.js.map +1 -1
  123. package/lib/providers/weblate/index.js +227 -6
  124. package/lib/providers/weblate/index.js.map +1 -1
  125. package/lib/providers/weblate/operations.js +3 -33
  126. package/lib/providers/weblate/operations.js.map +1 -1
  127. package/lib/providers/weblate/query.js +3 -6
  128. package/lib/providers/weblate/query.js.map +1 -1
  129. package/lib/providers/weblate/transport.js +2 -12
  130. package/lib/providers/weblate/transport.js.map +1 -1
  131. package/lib/service-credentials/config.js +2 -3
  132. package/lib/service-credentials/config.js.map +1 -1
  133. package/lib/shared/settings.js +14 -0
  134. package/lib/shared/settings.js.map +1 -0
  135. package/lib/typert.host.js +159 -60
  136. package/lib/typert.remote-client.d.ts +13 -11
  137. package/lib/typert.remote-client.js +98 -52
  138. package/lib/types/broker.d.ts +11 -3
  139. package/lib/types/client/bitrix24.d.ts +24 -2
  140. package/lib/types/client/confluence.d.ts +24 -4
  141. package/lib/types/client/index.d.ts +7 -6
  142. package/lib/types/client/integrations.d.ts +2 -2
  143. package/lib/types/client/jira.d.ts +25 -4
  144. package/lib/types/client/operator-card.d.ts +22 -0
  145. package/lib/types/client/operator-controls.d.ts +135 -0
  146. package/lib/types/client/testit.d.ts +14 -1
  147. package/lib/types/client/weblate.d.ts +14 -1
  148. package/lib/types/coerce.d.ts +14 -0
  149. package/lib/types/config.d.ts +4 -4
  150. package/lib/types/errors.d.ts +16 -0
  151. package/lib/types/index.d.ts +91 -15
  152. package/lib/types/providers/bitrix24/catalog.d.ts +8 -0
  153. package/lib/types/providers/bitrix24/config.d.ts +14 -23
  154. package/lib/types/providers/bitrix24/index.d.ts +37 -1
  155. package/lib/types/providers/confluence/catalog.d.ts +44 -8
  156. package/lib/types/providers/confluence/config.d.ts +39 -7
  157. package/lib/types/providers/confluence/credential-help.d.ts +9 -4
  158. package/lib/types/providers/confluence/dialect.d.ts +113 -0
  159. package/lib/types/providers/confluence/index.d.ts +82 -8
  160. package/lib/types/providers/confluence/operations.d.ts +14 -4
  161. package/lib/types/providers/confluence/storage.d.ts +28 -0
  162. package/lib/types/providers/confluence/transport.d.ts +10 -21
  163. package/lib/types/providers/jira/catalog.d.ts +49 -2
  164. package/lib/types/providers/jira/config.d.ts +37 -6
  165. package/lib/types/providers/jira/credential-help.d.ts +11 -3
  166. package/lib/types/providers/jira/dialect.d.ts +79 -0
  167. package/lib/types/providers/jira/index.d.ts +76 -19
  168. package/lib/types/providers/jira/jql.d.ts +14 -4
  169. package/lib/types/providers/jira/operations.d.ts +3 -0
  170. package/lib/types/providers/jira/transport.d.ts +6 -13
  171. package/lib/types/providers/shared/health.d.ts +18 -0
  172. package/lib/types/providers/shared/http.d.ts +9 -0
  173. package/lib/types/providers/shared/paths.d.ts +10 -0
  174. package/lib/types/providers/shared/payload.d.ts +26 -0
  175. package/lib/types/providers/teamcity/artifacts.d.ts +0 -2
  176. package/lib/types/providers/teamcity/index.d.ts +2 -0
  177. package/lib/types/providers/testit/catalog.d.ts +12 -0
  178. package/lib/types/providers/testit/index.d.ts +63 -2
  179. package/lib/types/providers/weblate/catalog.d.ts +19 -2
  180. package/lib/types/providers/weblate/index.d.ts +43 -1
  181. package/lib/types/shared/settings.d.ts +14 -0
  182. package/lib/types/types.d.ts +8 -0
  183. package/package.json +3 -3
@@ -1,19 +1,51 @@
1
1
  import { resolveCredentialHelp, } from "@yadsh/dsh-plugin-kit";
2
- import { IntegrationError } from "../../errors.js";
3
- import { CONFLUENCE_CAPABILITY_INFO, CONFLUENCE_OPERATIONS, enabledCapabilities, confluenceOperationCapability, } from "./catalog.js";
2
+ import { IntegrationError, recoverableResource } from "../../errors.js";
3
+ import { operationCapabilityServiceState } from "../../service-credentials/state.js";
4
+ import { healthFromFailure } from "../shared/health.js";
5
+ import { recordOf } from "../shared/payload.js";
6
+ import { assertServiceOperationAllowed, serviceBoundaryOf, serviceResourceDenied, } from "../shared/service-boundary.js";
7
+ import { CONFLUENCE_CAPABILITY_INFO, CONFLUENCE_OPERATIONS, CONFLUENCE_RESOURCE_KIND, confluenceOperationCapability, confluenceOperationMetadata, enabledCapabilities, } from "./catalog.js";
4
8
  import { CONFLUENCE_CREDENTIAL_HELP } from "./credential-help.js";
5
9
  import { credentialFromPlaintext, credentialInstance, ConfluenceTransport, } from "./transport.js";
6
- import { CONFLUENCE_HANDLERS, CONFLUENCE_PROJECTIONS, bodyLimit, commentChildrenPath, commentCollections, commentKind, commentPath, commentReplies, confluenceSource, numericId, offsetCursor, pageLimit, } from "./operations.js";
7
- import { spaceAllowed, } from "./config.js";
10
+ import { dialectOf } from "./dialect.js";
11
+ import { CONFLUENCE_HANDLERS, CONFLUENCE_PROJECTIONS, SPACE_TYPES, bodyLimit, commentCollections, commentChildrenPath, commentKind, commentPath, commentReplies, confluenceSource, isNumericSpace, listingCursor, numericId, offsetCursor, pageLimit, spaceKeys, spaceRef, } from "./operations.js";
12
+ import { confluenceInstance, spaceAllowed, } from "./config.js";
8
13
  export { credentialFromPlaintext, credentialInstance, } from "./transport.js";
9
14
  /**
10
- * Atlassian API tokens are long opaque strings, sometimes prefixed. A pasted
11
- * URL, a YAML snippet or a credential with whitespace is refused before
12
- * anything is sent upstream.
15
+ * Atlassian API tokens are long opaque strings, sometimes prefixed; a Server /
16
+ * Data Center personal access token is base64 and may carry `+`, `/` and
17
+ * padding. The shape a connection accepts is the dialect's own. A pasted URL, a
18
+ * YAML snippet or a credential with whitespace is refused before anything is
19
+ * sent upstream.
13
20
  */
14
- const TOKEN_SHAPE = /^[A-Za-z0-9._=+/-]{16,512}$/u;
15
- /** The Atlassian account the token belongs to; the pair is what authenticates. */
16
21
  const EMAIL_SHAPE = /^[^\s@]{1,64}@[^\s@.]+(?:\.[^\s@.]+)+$/u;
22
+ /**
23
+ * The `email:token` pair of a deployment-managed secret. Atlassian
24
+ * authenticates HTTP Basic over exactly this string, so it is the form the
25
+ * operator keeps in the secret file or the environment — one record, because
26
+ * the pair must not be assembled from two. The connect form never produces it:
27
+ * it collects the e-mail next to the token, and a pasted pair stays refused.
28
+ */
29
+ function splitBasicPair(raw) {
30
+ const at = raw.indexOf(":");
31
+ if (at <= 0)
32
+ return undefined;
33
+ const email = raw.slice(0, at);
34
+ if (!EMAIL_SHAPE.test(email))
35
+ return undefined;
36
+ return { email, token: raw.slice(at + 1) };
37
+ }
38
+ /**
39
+ * How many space keys one CQL `space in (...)` clause can carry. A service
40
+ * boundary wider than this cannot be asked for in one search, and a silently
41
+ * truncated one would answer with a lie by omission.
42
+ */
43
+ const SEARCH_SPACE_CAP = 20;
44
+ /** Page-addressed reads whose answer carries no space of its own to check. */
45
+ const PAGE_ADDRESSED = Object.freeze([
46
+ "pages.attachments",
47
+ "pages.versions",
48
+ ]);
17
49
  function accountName(data) {
18
50
  for (const key of ["displayName", "publicName", "email"]) {
19
51
  const value = data[key];
@@ -25,7 +57,50 @@ function accountName(data) {
25
57
  function textOf(value) {
26
58
  return typeof value === "string" && value !== "" ? value : undefined;
27
59
  }
28
- /** Confluence provider: operator-configured sites over an Atlassian API token. */
60
+ /**
61
+ * Which collection a comment of the marker dialect belongs to. Cloud hands out
62
+ * one endpoint per kind, so nothing has to be read off the comment there.
63
+ */
64
+ function commentMarker(row) {
65
+ const value = typeof row === "object" && row !== null
66
+ ? row["kind"]
67
+ : undefined;
68
+ return value === "footer" || value === "inline" ? value : undefined;
69
+ }
70
+ /**
71
+ * The identifier of one user as either product reports it: Cloud names an
72
+ * account id, a Server / Data Center installation the user key and login its
73
+ * directory uses. The same value is what a later read has to name the user by.
74
+ */
75
+ function identityOf(data) {
76
+ return (textOf(data["accountId"]) ??
77
+ textOf(data["userKey"]) ??
78
+ textOf(data["username"]));
79
+ }
80
+ /**
81
+ * Whether one space key stays inside the deployment's boundary. The profile's
82
+ * `resources.spaces` lists space keys — the same vocabulary the deployment's
83
+ * own allowlist and the CQL speak — and keys are compared case-insensitively,
84
+ * because operator config, the v2 API and CQL spell the same key in different
85
+ * cases.
86
+ */
87
+ export function spaceInBoundary(boundary, key) {
88
+ if (key === undefined)
89
+ return false;
90
+ const normalized = key.trim().toUpperCase();
91
+ if (normalized === "")
92
+ return false;
93
+ return (boundary[CONFLUENCE_RESOURCE_KIND] ?? []).some((entry) => entry.trim().toUpperCase() === normalized);
94
+ }
95
+ /**
96
+ * Confluence provider: operator-configured sites over an Atlassian API token
97
+ * (Cloud) or a personal access token (Server / Data Center).
98
+ *
99
+ * Which product answers at a site — and so which endpoints, which
100
+ * authentication scheme and which shape of body this provider speaks — is the
101
+ * site's own declared deployment type, never a guess made at connect or at run
102
+ * time.
103
+ */
29
104
  export class ConfluenceProvider {
30
105
  config;
31
106
  id = "confluence";
@@ -57,21 +132,33 @@ export class ConfluenceProvider {
57
132
  * from operator config, never from a tool argument, which is what keeps the
58
133
  * broker from dialling any host the caller names or authenticating as any
59
134
  * account the caller names.
135
+ *
136
+ * A deployment-managed secret cannot travel with a connect form, so on Cloud
137
+ * it arrives as the Basic pair Atlassian documents (`email:token`); the two
138
+ * forms can never be confused there, because an API token contains neither
139
+ * `@` nor `:`. A Server / Data Center personal access token is the secret
140
+ * alone, and its connection stores an empty e-mail: the instance's declared
141
+ * deployment type is what decides whether an account is required.
60
142
  */
61
143
  parseCredential(raw, options) {
62
- const token = raw.trim();
63
- if (!TOKEN_SHAPE.test(token)) {
64
- throw new IntegrationError("InvalidCredential", "Use an Atlassian API token");
144
+ // The instance decides what this connection is allowed to look like, so it
145
+ // is resolved before the secret is judged.
146
+ const instance = this.resolveInstance(options?.["instanceId"]);
147
+ const dialect = dialectOf(instance);
148
+ const provided = raw.trim();
149
+ const pair = options?.["email"] === undefined ? splitBasicPair(provided) : undefined;
150
+ const token = pair === undefined ? provided : pair.token;
151
+ if (!dialect.tokenShape.test(token)) {
152
+ throw new IntegrationError("InvalidCredential", `Use a Confluence ${dialect.credentialLabel}`);
65
153
  }
66
- const email = (options?.["email"] ?? "").trim();
67
- if (!EMAIL_SHAPE.test(email)) {
154
+ const email = (pair === undefined ? options?.["email"] : pair.email)?.trim();
155
+ if (dialect.requiresEmail && !EMAIL_SHAPE.test(email ?? "")) {
68
156
  throw new IntegrationError("InvalidCredential", "Use the e-mail of the Atlassian account the token belongs to");
69
157
  }
70
- const instance = this.resolveInstance(options?.["instanceId"]);
71
158
  return {
72
159
  credential: JSON.stringify({
73
160
  instanceId: instance.id,
74
- email,
161
+ email: email ?? "",
75
162
  token,
76
163
  }),
77
164
  portal: instance.baseUrl,
@@ -80,15 +167,39 @@ export class ConfluenceProvider {
80
167
  operationCapability(operation) {
81
168
  return confluenceOperationCapability(operation);
82
169
  }
170
+ operationMetadata(operation) {
171
+ return confluenceOperationMetadata(operation);
172
+ }
173
+ /** Every space-scoped read is bounded by the profile's space keys. */
174
+ resourceBoundaryKind(operation) {
175
+ return CONFLUENCE_OPERATIONS[operation]?.security
176
+ .requiresResourceBoundary === true
177
+ ? CONFLUENCE_RESOURCE_KIND
178
+ : undefined;
179
+ }
180
+ /**
181
+ * Portal of a configured site. An empty id means "the only site", the same
182
+ * rule `parseCredential` applies, so deployment configuration and the
183
+ * connect form name sites alike.
184
+ */
185
+ instancePortal(instanceId) {
186
+ const instances = this.config.confluence.instances;
187
+ const id = instanceId.trim();
188
+ if (id === "") {
189
+ return instances.length === 1 ? instances[0]?.baseUrl : undefined;
190
+ }
191
+ return confluenceInstance(this.config.confluence, id)?.baseUrl;
192
+ }
193
+ capabilityServiceState(capability) {
194
+ return operationCapabilityServiceState(CONFLUENCE_OPERATIONS, capability);
195
+ }
83
196
  async validate(context) {
84
197
  const credential = credentialFromPlaintext(context.credential);
85
198
  const instance = credentialInstance(this.config.confluence, credential);
86
- // The connected user is the one read Confluence only serves over v1, and it
87
- // is also the cheapest proof that this token may use Confluence at all.
88
- const { data } = await this.transport.getJson(instance, credential, "/wiki/rest/api/user/current");
89
- const accountId = textOf(data["accountId"]) ??
90
- textOf(data["userKey"]) ??
91
- textOf(data["username"]);
199
+ // The connected user is the one read both products serve, and it is also
200
+ // the cheapest proof that this token may use Confluence at all.
201
+ const { data } = await this.transport.getJson(instance, credential, dialectOf(instance).currentUserPath);
202
+ const accountId = identityOf(data);
92
203
  if (accountId === undefined) {
93
204
  throw new IntegrationError("ProviderUnavailable", "Provider identity is unavailable");
94
205
  }
@@ -99,6 +210,34 @@ export class ConfluenceProvider {
99
210
  capabilities: this.capabilities,
100
211
  };
101
212
  }
213
+ /**
214
+ * Health of a deployment-managed token. The probe reads only the identity
215
+ * endpoint the personal validation reads, so it never changes upstream state;
216
+ * Confluence exposes no token-scope introspection, so the answer is healthy
217
+ * with a warning — the local service ceiling stays the whole local boundary.
218
+ */
219
+ async validateServiceCredential(context) {
220
+ const credential = credentialFromPlaintext(context.credential);
221
+ const instance = credentialInstance(this.config.confluence, credential);
222
+ let data;
223
+ try {
224
+ const response = await this.transport.getJson(instance, credential, dialectOf(instance).currentUserPath);
225
+ data = response.data;
226
+ }
227
+ catch (error) {
228
+ return healthFromFailure(error);
229
+ }
230
+ const id = identityOf(data);
231
+ return {
232
+ status: "healthy",
233
+ ...(id === undefined
234
+ ? {}
235
+ : { upstreamIdentity: { id, label: accountName(data) } }),
236
+ warnings: [
237
+ "Confluence did not report the token scopes; the local service ceiling still applies",
238
+ ],
239
+ };
240
+ }
102
241
  async execute(context, operation, input) {
103
242
  const credential = credentialFromPlaintext(context.credential);
104
243
  const instance = credentialInstance(this.config.confluence, credential);
@@ -111,52 +250,88 @@ export class ConfluenceProvider {
111
250
  throw new IntegrationError("InvalidRequest", "Unsupported Confluence operation");
112
251
  }
113
252
  const flags = this.config.confluence;
114
- const request = handler(input, {
253
+ // Ceiling first, then the boundary: what the operation is decides before
254
+ // where it may read.
255
+ if (context.credentialSource === "service") {
256
+ assertServiceOperationAllowed(definition.security, "This Confluence operation is not available through the service credential");
257
+ }
258
+ const boundary = serviceBoundaryOf(context);
259
+ if (boundary !== undefined && operation === "spaces.list") {
260
+ return this.listBoundedSpaces(instance, credential, boundary, input, flags);
261
+ }
262
+ if (boundary !== undefined && PAGE_ADDRESSED.includes(operation)) {
263
+ // These answers carry no space of their own, so the page's space is
264
+ // resolved first and verified before anything is fetched for the answer.
265
+ // Comments resolve their page inside their own read, a page read inside
266
+ // its own.
267
+ await this.assertPageReachable(instance, credential, numericId(input["pageId"], "pageId"), flags, boundary, dialectOf(instance));
268
+ }
269
+ if (boundary !== undefined && operation === "spaces.get") {
270
+ const ref = spaceRef(input["space"]);
271
+ // A key is refused without a call; a numeric id is resolved to its key
272
+ // by the read itself, which verifies before anything is returned.
273
+ if (!isNumericSpace(ref) && !spaceInBoundary(boundary, ref)) {
274
+ throw serviceResourceDenied();
275
+ }
276
+ }
277
+ // In service mode a search is narrowed to the boundary before the handler
278
+ // builds the CQL, so the restriction travels upstream.
279
+ const prepared = boundary !== undefined && operation === "search.run"
280
+ ? this.boundedSearchInput(input, boundary, flags)
281
+ : input;
282
+ const dialect = dialectOf(instance);
283
+ const request = handler(prepared, {
115
284
  externalUserId: context.externalUserId,
116
285
  flags,
286
+ dialect,
117
287
  });
118
288
  if (operation === "pages.get") {
119
- return this.readPage(instance, credential, request, flags, input);
289
+ return this.readPage(instance, credential, request, flags, prepared, boundary, dialect);
120
290
  }
121
291
  if (operation === "pages.comments") {
122
- return this.readComments(instance, credential, request, flags, input);
292
+ return this.readComments(instance, credential, flags, prepared, boundary, dialect);
123
293
  }
124
294
  if (operation === "spaces.get") {
125
- return this.readSpace(instance, credential, request, flags);
295
+ return this.readSpace(instance, credential, request, flags, boundary);
126
296
  }
127
- return this.readList(instance, credential, request, operation, definition.cursor, flags, input);
297
+ return this.readList(instance, credential, request, operation, definition.cursor, flags, prepared, boundary);
128
298
  }
129
299
  /** One list read, with its cursor and with the space policy re-applied. */
130
- async readList(instance, credential, request, operation, cursorMode, flags, input) {
300
+ async readList(instance, credential, request, operation, cursorMode, flags, input, boundary) {
131
301
  const projection = CONFLUENCE_PROJECTIONS[operation];
132
302
  const response = await this.transport.getJson(instance, credential, request.path, request.query);
133
303
  const answer = projection?.(response.data, {
134
304
  ...this.projectionContext(flags, instance, input),
135
305
  start: cursorMode === "offset" ? offsetCursor(input["cursor"]) : undefined,
136
306
  }) ?? { source: {} };
137
- // The CQL already restricts the search to allowed spaces, and the space
138
- // listing asks for them by key. This filter is the second lock: a row whose
139
- // space cannot be read as an allowed key is dropped rather than shown.
140
- if (operation === "search.run" && flags.allowedSpaces.length > 0) {
307
+ // The CQL already restricts the search to allowed spaces — and, in service
308
+ // mode, to the boundary. This filter is the second lock: a row whose space
309
+ // cannot be read as an allowed key is dropped rather than shown.
310
+ if (operation === "search.run" &&
311
+ (flags.allowedSpaces.length > 0 || boundary !== undefined)) {
141
312
  const items = Array.isArray(answer["items"]) ? answer["items"] : [];
142
- answer["items"] = items.filter((item) => this.itemSpaceAllowed(item, flags));
313
+ answer["items"] = items.filter((item) => this.itemSpaceReachable(item, flags, boundary));
143
314
  }
144
- const nextCursor = cursorMode === "upstream" ? response.page?.nextCursor : undefined;
315
+ // An offset-paged read counts its own rows, but the product's own `next`
316
+ // link is authoritative when it has one: it says where the next page really
317
+ // begins, which matters when a row of this page was dropped by a policy.
318
+ const upstream = response.page?.nextCursor;
319
+ const nextCursor = cursorMode === "upstream"
320
+ ? upstream
321
+ : (answer["nextCursor"] ?? upstream);
145
322
  return nextCursor === undefined ? answer : { ...answer, nextCursor };
146
323
  }
147
324
  /**
148
325
  * A page read is answered with the page's space, because that is what the
149
326
  * operator allowlist is written in — and a page whose space the policy does
150
- * not allow is refused here, after the read and before the model sees it.
327
+ * not allow is refused here, after the read and before the model sees it. In
328
+ * service mode the boundary is verified on the same resolved space.
151
329
  */
152
- async readPage(instance, credential, request, flags, input) {
330
+ async readPage(instance, credential, request, flags, input, boundary, dialect) {
153
331
  const projection = CONFLUENCE_PROJECTIONS["pages.get"];
154
332
  const response = await this.transport.getJson(instance, credential, request.path, request.query);
155
- const spaceId = textOf(response.data["spaceId"]);
156
- const space = spaceId === undefined
157
- ? {}
158
- : await this.readSpaceFields(instance, credential, spaceId);
159
- this.assertSpaceAllowed(flags, textOf(space["key"]));
333
+ const space = await this.spaceOfPage(instance, credential, response.data, dialect);
334
+ this.assertSpaceReachable(flags, textOf(space["key"]), boundary);
160
335
  return (projection?.(response.data, {
161
336
  ...this.projectionContext(flags, instance, input),
162
337
  space,
@@ -168,35 +343,48 @@ export class ConfluenceProvider {
168
343
  * cost one request per parent comment, so a discussion wider than the
169
344
  * deployment cap is answered with the parents it did load and says so.
170
345
  */
171
- async readComments(instance, credential, request, flags, input) {
346
+ async readComments(instance, credential, flags, input, boundary, dialect) {
172
347
  const projection = CONFLUENCE_PROJECTIONS["pages.comments"];
173
348
  const pageId = numericId(input["pageId"], "pageId");
174
349
  const kind = commentKind(input["kind"]);
175
- if (flags.allowedSpaces.length > 0) {
176
- await this.assertPageAllowedBySpace(instance, credential, pageId, flags);
350
+ if (flags.allowedSpaces.length > 0 || boundary !== undefined) {
351
+ await this.assertPageReachable(instance, credential, pageId, flags, boundary, dialect);
177
352
  }
178
353
  const includeReplies = typeof input["includeReplies"] === "boolean" && input["includeReplies"];
179
- const collections = commentCollections(kind);
354
+ // Cloud keeps the two kinds in two collections, so a kind selects one; a
355
+ // Server / Data Center installation keeps both in one and marks each
356
+ // comment, so every kind is read from that one collection.
357
+ const collections = dialect.commentKinds === "path" ? commentCollections(kind) : ["footer"];
358
+ const cursor = listingCursor(input["cursor"], dialect);
359
+ const limit = pageLimit(input["limit"], flags);
180
360
  const items = [];
181
361
  const cursors = {};
182
362
  let repliesTruncated = false;
183
363
  for (const collection of collections) {
184
- const response = await this.transport.getJson(instance, credential, commentPath(pageId, collection), request.query);
364
+ const call = commentPath(dialect, pageId, collection, cursor, limit);
365
+ const response = await this.transport.getJson(instance, credential, call.path, call.query);
185
366
  const context = {
186
367
  ...this.projectionContext(flags, instance, input),
187
368
  pageId,
188
369
  kind: collection,
189
370
  };
190
371
  const projected = projection?.(response.data, context) ?? {};
191
- const rows = Array.isArray(projected["items"]) ? projected["items"] : [];
372
+ const projectedRows = Array.isArray(projected["items"])
373
+ ? projected["items"]
374
+ : [];
375
+ // The marker dialect answered one collection for every kind, so a kind
376
+ // the caller named is applied to the rows the product marked.
377
+ const rows = dialect.commentKinds === "marker" && kind !== "all"
378
+ ? projectedRows.filter((row) => commentMarker(row) === kind)
379
+ : projectedRows;
192
380
  const loaded = includeReplies
193
- ? await this.withReplies(instance, credential, rows, collection, flags, context)
381
+ ? await this.withReplies(instance, credential, rows, collection, flags, context, dialect)
194
382
  : { items: rows, truncated: false };
195
383
  repliesTruncated = repliesTruncated || loaded.truncated;
196
384
  items.push(...loaded.items);
197
- const cursor = response.page?.nextCursor;
198
- if (cursor !== undefined)
199
- cursors[collection] = cursor;
385
+ const next = response.page?.nextCursor;
386
+ if (next !== undefined)
387
+ cursors[collection] = next;
200
388
  }
201
389
  const answer = {
202
390
  source: confluenceSource(instance, { pageId }),
@@ -206,12 +394,12 @@ export class ConfluenceProvider {
206
394
  return { ...answer, cursors, repliesTruncated };
207
395
  return {
208
396
  ...answer,
209
- nextCursor: cursors[kind],
397
+ nextCursor: cursors[collections[0] ?? "footer"],
210
398
  ...(repliesTruncated ? { repliesTruncated: true } : {}),
211
399
  };
212
400
  }
213
401
  /** One children read per parent comment, capped by the deployment. */
214
- async withReplies(instance, credential, rows, collection, flags, context) {
402
+ async withReplies(instance, credential, rows, collection, flags, context, dialect) {
215
403
  const cap = Math.max(flags.maxReplyParents, 0);
216
404
  const items = [];
217
405
  for (const [index, row] of rows.entries()) {
@@ -224,11 +412,11 @@ export class ConfluenceProvider {
224
412
  items.push(row);
225
413
  continue;
226
414
  }
227
- const response = await this.transport.getJson(instance, credential, commentChildrenPath(collection, numericId(id, "commentId")), {
228
- "body-format": "atlas_doc_format",
229
- limit: pageLimit(undefined, flags),
230
- sort: "created-date",
231
- });
415
+ const call = commentChildrenPath(dialect,
416
+ // A row of the marker dialect names its own kind; a reply belongs to the
417
+ // collection its parent was read from.
418
+ commentMarker(row) ?? collection, numericId(id, "commentId"), undefined, pageLimit(undefined, flags));
419
+ const response = await this.transport.getJson(instance, credential, call.path, call.query);
232
420
  items.push({
233
421
  ...row,
234
422
  replies: commentReplies(response.data, collection, context),
@@ -237,7 +425,7 @@ export class ConfluenceProvider {
237
425
  return { items, truncated: rows.length > cap };
238
426
  }
239
427
  /** One space, by id or by the key the listing endpoint resolves. */
240
- async readSpace(instance, credential, request, flags) {
428
+ async readSpace(instance, credential, request, flags, boundary) {
241
429
  const projection = CONFLUENCE_PROJECTIONS["spaces.get"];
242
430
  const response = await this.transport.getJson(instance, credential, request.path, request.query);
243
431
  const answer = projection?.(response.data, {
@@ -246,31 +434,152 @@ export class ConfluenceProvider {
246
434
  bodyLimit: bodyLimit(undefined, flags),
247
435
  }) ?? {};
248
436
  const space = answer["space"];
249
- this.assertSpaceAllowed(flags, typeof space === "object" && space !== null
437
+ this.assertSpaceReachable(flags, typeof space === "object" && space !== null
250
438
  ? textOf(space["key"])
251
- : undefined);
439
+ : undefined, boundary);
252
440
  return answer;
253
441
  }
442
+ /**
443
+ * A service search is narrowed to the boundary before the handler builds the
444
+ * CQL: an offset-paginated search whose out-of-boundary rows were dropped
445
+ * afterwards would answer pages that shrink and cursors that lose their
446
+ * place. A space the caller names outside the boundary is refused rather
447
+ * than dropped, and the filter in `readList` stays as the second lock.
448
+ */
449
+ boundedSearchInput(input, boundary, flags) {
450
+ const requested = spaceKeys(input["spaces"], "spaces");
451
+ for (const key of requested) {
452
+ if (!spaceInBoundary(boundary, key)) {
453
+ throw serviceResourceDenied();
454
+ }
455
+ }
456
+ if (requested.length > 0)
457
+ return input;
458
+ // Without spaces the caller named, the search asks for the boundary itself
459
+ // — still narrowed by the deployment allowlist, which binds the agent
460
+ // whatever credential it spends.
461
+ const allowlist = flags.allowedSpaces;
462
+ const spaces = (boundary[CONFLUENCE_RESOURCE_KIND] ?? [])
463
+ .map((key) => key.trim().toUpperCase())
464
+ .filter((key) => allowlist.length === 0 || allowlist.includes(key));
465
+ // An empty intersection means the two administrator lists disagree; a list
466
+ // wider than one CQL clause cannot be asked for at all. Both refuse rather
467
+ // than answer with an unbounded or silently truncated search.
468
+ if (spaces.length === 0 || spaces.length > SEARCH_SPACE_CAP) {
469
+ throw serviceResourceDenied();
470
+ }
471
+ return { ...input, spaces };
472
+ }
473
+ /**
474
+ * The bounded space listing. A service profile names the spaces it covers,
475
+ * so the listing is built from that list instead of from whatever the shared
476
+ * account can reach; a space the service token cannot see is reported as
477
+ * unavailable rather than silently dropped. The answer does not page: its
478
+ * size is the boundary the administrator defined, not upstream's.
479
+ */
480
+ async listBoundedSpaces(instance, credential, boundary, input, flags) {
481
+ const requested = spaceKeys(input["keys"], "keys");
482
+ for (const key of requested) {
483
+ if (!spaceInBoundary(boundary, key)) {
484
+ throw serviceResourceDenied();
485
+ }
486
+ }
487
+ const allowlist = flags.allowedSpaces;
488
+ const entries = (boundary[CONFLUENCE_RESOURCE_KIND] ?? []).filter((key) => {
489
+ const normalized = key.trim().toUpperCase();
490
+ return ((requested.length === 0 || requested.includes(normalized)) &&
491
+ (allowlist.length === 0 || allowlist.includes(normalized)));
492
+ });
493
+ if (entries.length === 0) {
494
+ throw serviceResourceDenied();
495
+ }
496
+ const type = textOf(input["type"]);
497
+ if (type !== undefined && !SPACE_TYPES.includes(type)) {
498
+ throw new IntegrationError("InvalidRequest", "type is invalid");
499
+ }
500
+ const projection = CONFLUENCE_PROJECTIONS["spaces.list"];
501
+ const items = [];
502
+ const unavailable = [];
503
+ for (const key of entries) {
504
+ try {
505
+ const call = dialectOf(instance).spaceList({
506
+ keys: [key],
507
+ type,
508
+ cursor: undefined,
509
+ limit: 2,
510
+ });
511
+ const { data } = await this.transport.getJson(instance, credential, call.path, call.query);
512
+ const projected = projection?.(data, { flags, instance }) ?? {};
513
+ const rows = Array.isArray(projected["items"])
514
+ ? projected["items"]
515
+ : [];
516
+ items.push(...rows);
517
+ }
518
+ catch (error) {
519
+ if (!recoverableResource(error))
520
+ throw error;
521
+ unavailable.push(key);
522
+ }
523
+ }
524
+ return {
525
+ source: confluenceSource(instance),
526
+ items,
527
+ serviceScoped: true,
528
+ ...(unavailable.length === 0
529
+ ? {}
530
+ : { unavailableResources: unavailable }),
531
+ };
532
+ }
254
533
  /** The fields a space contributes to a page answer, plus its policy key. */
255
- async readSpaceFields(instance, credential, spaceId) {
256
- const { data } = await this.transport.getJson(instance, credential,
257
- // An id that arrived from upstream is not trusted as a path segment.
258
- `/wiki/api/v2/spaces/${numericId(spaceId, "spaceId")}`, {});
534
+ async readSpaceFields(instance, credential, spaceId, dialect) {
535
+ const call = dialect.spacePath(numericId(spaceId, "spaceId"));
536
+ const { data } = await this.transport.getJson(instance, credential, call.path, call.query);
259
537
  return data;
260
538
  }
261
539
  /**
262
- * The space of a page the call is about. Only asked for when the deployment
263
- * narrowed spaces: without an allowlist there is no policy to enforce, and
264
- * the extra read would be spent for nothing.
540
+ * The space a page belongs to, as the product reports it. Cloud names the
541
+ * space by an id on the page, so it is resolved with a second read; a
542
+ * Server / Data Center installation carries the space itself on the page, and
543
+ * that read would be spent for nothing.
265
544
  */
266
- async assertPageAllowedBySpace(instance, credential, pageId, flags) {
267
- const { data } = await this.transport.getJson(instance, credential, `/wiki/api/v2/pages/${pageId}`, {});
268
- const spaceId = textOf(data["spaceId"]);
269
- if (spaceId === undefined) {
545
+ async spaceOfPage(instance, credential, page, dialect) {
546
+ const inline = recordOf(page["space"]);
547
+ if (Object.keys(inline).length > 0)
548
+ return inline;
549
+ const spaceId = textOf(page["spaceId"]);
550
+ return spaceId === undefined
551
+ ? {}
552
+ : await this.readSpaceFields(instance, credential, spaceId, dialect);
553
+ }
554
+ /**
555
+ * The space of a page the call is about. Asked for whenever a policy needs
556
+ * it: the deployment allowlist, or — in service mode — the boundary, which is
557
+ * always there. Without either there is no policy to enforce, and the extra
558
+ * reads would be spent for nothing.
559
+ */
560
+ async assertPageReachable(instance, credential, pageId, flags, boundary, dialect) {
561
+ const call = dialect.pageSpacePath(pageId);
562
+ const { data } = await this.transport.getJson(instance, credential, call.path, call.query);
563
+ const space = await this.spaceOfPage(instance, credential, data, dialect);
564
+ const key = textOf(space["key"]);
565
+ if (key === undefined) {
566
+ // A page answer that names no space at all is a page that is not there —
567
+ // or one the credentials may not see, which Confluence answers the same
568
+ // way on purpose.
270
569
  throw new IntegrationError("ResourceNotFound", "Confluence page not found");
271
570
  }
272
- const space = await this.readSpaceFields(instance, credential, spaceId);
273
- this.assertSpaceAllowed(flags, textOf(space["key"]));
571
+ this.assertSpaceReachable(flags, key, boundary);
572
+ }
573
+ /**
574
+ * Both space policies of one read, in the order a refusal should name them:
575
+ * the deployment allowlist first, the service boundary — when the call runs
576
+ * on the managed credential — second.
577
+ */
578
+ assertSpaceReachable(flags, key, boundary) {
579
+ this.assertSpaceAllowed(flags, key);
580
+ if (boundary !== undefined && !spaceInBoundary(boundary, key)) {
581
+ throw serviceResourceDenied();
582
+ }
274
583
  }
275
584
  /**
276
585
  * A space outside the operator allowlist is refused as a policy decision, not
@@ -283,16 +592,19 @@ export class ConfluenceProvider {
283
592
  throw new IntegrationError("OperationDeniedByPolicy", "Space is outside the allowlist of this deployment");
284
593
  }
285
594
  /** The space of one search row, as the projection resolved it. */
286
- itemSpaceAllowed(item, flags) {
595
+ itemSpaceReachable(item, flags, boundary) {
287
596
  const space = typeof item === "object" && item !== null
288
597
  ? item["space"]
289
598
  : undefined;
290
599
  const key = typeof space === "object" && space !== null
291
600
  ? textOf(space["key"])
292
601
  : undefined;
293
- // An empty allowlist never reaches here; a row whose space is unreadable
294
- // fails closed, so a listing can only show what this policy proves.
295
- return flags.allowedSpaces.length > 0 && spaceAllowed(flags, key);
602
+ // A row whose space is unreadable fails closed, so a listing can only show
603
+ // what a policy proves: the deployment allowlist, or — in service mode —
604
+ // the boundary as well.
605
+ if (!spaceAllowed(flags, key))
606
+ return false;
607
+ return boundary === undefined || spaceInBoundary(boundary, key);
296
608
  }
297
609
  projectionContext(flags, instance, input) {
298
610
  return {
@@ -324,5 +636,7 @@ export class ConfluenceProvider {
324
636
  return only;
325
637
  }
326
638
  }
639
+ /** A missing or forbidden space inside a boundary is reported, not fatal. */
640
+ /** Map an upstream failure of the probe onto a health status. */
327
641
  export default ConfluenceProvider;
328
642
  //# sourceMappingURL=index.js.map