Add payload protection capability to IDE protocol (#2991)

Also adds `/info` request type for sourcing information about supported protocol versions and other IDE endpoint capabilities.

docs/specs/IDE-execution.md

@@ -18,12 +18,13 @@ For IDE execution to work, two conditions need to be fulfilled:
 1. DCP needs to be told how to contact the IDE (what is the **IDE session endpoint**, specifically).
 1. The `ExecutionType` property for the `Executable` object needs to be set to `IDE` (default is `Process`, which indicates OS process-based execution).
 
-Only one IDE (one IDE session endpoint) is supported per DCP instance. The IDE session endpoint is provided to DCP via environment variables (both required if IDE execution is used):
+Only one IDE (one IDE session endpoint) is supported per DCP instance. The IDE session endpoint is configured via environment variables:
 
 | Environment variable | Value |
 | ----- | ----- |
-| `DEBUG_SESSION_PORT` | The port DCP should use to talk to the IDE session endpoint. DCP will use `http://localhost:<value of DEBUG_SESSION_PORT>` as the IDE session endpoint base URL. |
-| `DEBUG_SESSION_TOKEN` | Security (bearer) token for talking to the IDE session endpoint. This token will be attached to every request via Authorization HTTP header. |
+| `DEBUG_SESSION_PORT` | The port DCP should use to talk to the IDE session endpoint. DCP will use `http://localhost:<value of DEBUG_SESSION_PORT>` as the IDE session endpoint base URL. Required. |
+| `DEBUG_SESSION_TOKEN` | Security (bearer) token for talking to the IDE session endpoint. This token will be attached to every request via Authorization HTTP header. Required. |
+| `DEBUG_SESSION_SERVER_CERTIFICATE` | If present, provides base64-encoded server certificate used for authenticating IDE endpoint and securing the communication via TLS. <br/> The certificate can be self-signed, but it must include subject alternative name, set to "localhost". Setting canonical name (`cn`) is not sufficient. <br/> If the certificate is provided, all communication with the IDE will occur via `https` and `wss` (the latter for the session change notifications). There will be NO fallback to `http` or `ws` or un-authenticated mode. Using `https` and `wss` is optional but strongly recommended. |
 
 > Note: the most important use case for the IDE execution is to facilitate application services debugging. The word "debug" appears in environment variable names that DCP uses to connect to IDE session endpoint, but IDE execution does not always mean that the service is running under a debugger.
 
@@ -85,9 +86,9 @@ The payload is best explained using an example:
 **Response** <br/>
 If the execution session is created successfully, the return status code should be 200 OK or 201 Created. The response should include the created run session identifier in the `Location` header:
 
-`Location: http://localhost:<IDE endpoint port>/run_session/<new run ID>`
+`Location: https://localhost:<IDE endpoint port>/run_session/<new run ID>`
 
-If the session cannot be created, appropriate 4xx or 5xx status code should be returned. The response might also return a description of the problem as part of the status line, or in the response body.
+If the session cannot be created, appropriate 4xx or 5xx status code should be returned. The response might also return a description of the problem as part of the status line, [or in the response body](#error-reporting).
 
 ### Launch configurations
 
@@ -124,7 +125,7 @@ If the session exists and can be stopped, the IDE should reply with 200 OK statu
 
 If the session does not exist, the IDE should reply with 204 No Content.
 
-If the session cannot be stopped, appropriate 4xx or 5xx status code should be returned. The response might also return a description of the problem as part of the status line, or in the response body.
+If the session cannot be stopped, appropriate 4xx or 5xx status code should be returned. The response might also return a description of the problem as part of the status line, [or in the response body](#error-reporting).
 
 ### Subscribe to session change notifications request
 
@@ -140,6 +141,30 @@ Used by DCP to subscribe to run session change notification.
 **Response** <br/>
 If successful, the connection should be upgraded to a web sockets connection, which will be then used by the IDE to stream run session change notifications to DCP. See next paragraph for description of possible change notifications.
 
+### IDE endpoint information request
+
+Used by DCP to get information about capabilities of the IDE run session endpoint. 
+
+**HTTP verb and path** <br/>
+`GET /info`
+
+**Headers** <br/>
+`Authorization: Bearer <security token>`
+
+**Response** <br/>
+A JSON document describing the capabilities of the IDE run session endpoint. For example:
+```jsonc
+{
+    "protocols_supported": [ "2024-03-03" ]
+}
+```
+
+The properties of the IDE endpoint information document are:
+
+| Property | Description | Type |
+| --- | --------- | --- |
+| `protocols_supported` | List of protocols supported by the IDE endpoint. See [protocol versioning](#protocol-versioning) for more information. | `string[]` |
+
 ## Run session change notifications
 
 The run session change notifications are delivered from IDE to DCP via the web socket connection. The format of notification is JSON Lines (one JSON object per line of text).
@@ -208,7 +233,7 @@ The value of the `error` property is an `ErrorDetail` object with the following
 | `message` | A human-readable message explaining the nature of the error, and providing suggestions for resolution. DCP will display this message as part of the Aspire application host execution log. | Required |
 | `details` | An array of `ErrorDetail` objects providing additional information about the error. | Optional |
 
-## Request versioning
+## Protocol versioning
 
 When making a request to the IDE, DCP will include an `api-version` parameter to indicate the version of the protocol used, for example: 
 
@@ -218,4 +243,6 @@ The version always follows `YYYY-mm-dd` format and allows for older/equal/newer
 
 If the protocol version is old (no longer supported by the IDE), the IDE should return a 400 Bad Request response with the message indicating that the developer should consider upgrading the Aspire libraries and tooling used by their application.
 
-If the protocol version is newer than the latest the IDE supports, the IDE should make an attempt to parse the request according to its latest supported version. If that fails, it should return 400 Bad Request error.
+If the protocol version is newer than the latest the IDE supports, the IDE should make an attempt to parse the request according to its latest supported version. If that fails, the IDE should return `400 Bad Request` error.
+
+> The `api-version` parameter will be attached to all requests except the `/info` request (which is designed to facilitate protocol version negotiation).