Add security prerequisites support (#717)

Author: delvedor

compiler/model/metamodel.ts

@@ -366,6 +366,10 @@ export class Endpoint {
   visibility?: Visibility
   accept?: string[]
   contentType?: string[]
+  securityPrerequisites?: {
+    index?: string[]
+    cluster?: string[]
+  }
 }
 
 export class UrlTemplate {

compiler/model/utils.ts

@@ -544,7 +544,7 @@ export function hoistRequestAnnotations (
   request: model.Request, jsDocs: JSDoc[], mappings: Record<string, model.Endpoint>, response: model.TypeName | null
 ): void {
   const knownRequestAnnotations = [
-    'since', 'rest_spec_name', 'stability', 'visibility', 'behavior', 'class_serializer', 'doc_id'
+    'since', 'rest_spec_name', 'stability', 'visibility', 'behavior', 'class_serializer', 'security_prerequisites_index', 'security_prerequisites_cluster', 'doc_id'
   ]
   // in most of the cases the jsDocs comes in a single block,
   // but it can happen that the user defines multiple single line jsDoc.
@@ -584,6 +584,33 @@ export function hoistRequestAnnotations (
     } else if (tag === 'since') {
       assert(jsDocs, semver.valid(value), `Request ${request.name.name}'s @since is not valid semver: ${value}`)
       endpoint.since = value
+    } else if (tag === 'security_prerequisites_index') {
+      const privileges = [
+        'all', 'auto_configure', 'create', 'create_doc', 'create_index', 'delete', 'delete_index', 'index',
+        'maintenance', 'manage', 'manage_follow_index', 'manage_ilm', 'manage_leader_index', 'monitor',
+        'read', 'read_cross_cluster', 'view_index_metadata', 'write'
+      ]
+      const values = value.split(',').map(v => v.trim())
+      for (const v of values) {
+        assert(jsDocs, privileges.includes(v), `The index privilege '${v}' does not exists.`)
+      }
+      endpoint.securityPrerequisites = endpoint.securityPrerequisites ?? {}
+      endpoint.securityPrerequisites.index = values
+    } else if (tag === 'security_prerequisites_cluster') {
+      const privileges = [
+        'all', 'cancel_task', 'create_snapshot', 'grant_api_key', 'manage', 'manage_api_key', 'manage_ccr',
+        'manage_ilm', 'manage_index_templates', 'manage_ingest_pipelines', 'manage_logstash_pipelines',
+        'manage_ml', 'manage_oidc', 'manage_own_api_key', 'manage_pipeline', 'manage_rollup', 'manage_saml',
+        'manage_security', 'manage_service_account', 'manage_slm', 'manage_token', 'manage_transform',
+        'manage_watcher', 'monitor', 'monitor_ml', 'monitor_rollup', 'monitor_snapshot', 'monitor_text_structure',
+        'monitor_transform', 'monitor_watcher', 'read_ccr', 'read_ilm', 'read_pipeline', 'read_slm', 'transport_client'
+      ]
+      const values = value.split(',').map(v => v.trim())
+      for (const v of values) {
+        assert(jsDocs, privileges.includes(v), `The cluster privilege '${v}' does not exists.`)
+      }
+      endpoint.securityPrerequisites = endpoint.securityPrerequisites ?? {}
+      endpoint.securityPrerequisites.cluster = values
     } else if (tag === 'doc_id') {
       assert(jsDocs, value.trim() !== '', `Request ${request.name.name}'s @doc_id is cannot be empty`)
       endpoint.docId = value

docs/modeling-guide.md

@@ -484,3 +484,35 @@ export interface Request<TDocument> extends RequestBase {
   body?: TDocument
 }
 ```
+
+#### `@security_prerequisites_index`
+
+If an endpoint has some index security prerequisites to satisfy, you can specify them here with a comma separated list.
+
+```ts
+/**
+ * @rest_spec_name indices.create
+ * @since 0.0.0
+ * @stability stable
+ * @security_prerequisites_index create_index, manage
+ */
+export interface Request extends RequestBase {
+ ...
+}
+```
+
+#### `@security_prerequisites_cluster`
+
+If an endpoint has some cluster security prerequisites to satisfy, you can specify them here with a comma separated list.
+
+```ts
+/**
+ * @rest_spec_name cluster.state
+ * @since 1.3.0
+ * @stability stable
+ * @security_prerequisites_cluster monitor, manage
+ */
+export interface Request extends RequestBase {
+ ...
+}
+```

output/schema/schema.json

@@ -30,6 +30,7 @@ import { Time } from '@_types/Time'
  * @rest_spec_name cluster.state
  * @since 1.3.0
  * @stability stable
+ * @security_prerequisites_cluster monitor, manage
  */
 export interface Request extends RequestBase {
   path_parts: {

specification/cluster/state/ClusterStateRequest.ts

@@ -29,6 +29,7 @@ import { Time } from '@_types/Time'
  * @rest_spec_name indices.create
  * @since 0.0.0
  * @stability stable
+ * @security_prerequisites_index create_index, manage
  */
 export interface Request extends RequestBase {
   path_parts: {