Resolve upstream conflicts

specification.md

@@ -105,9 +105,9 @@ ServerToAgent Protobuf messages:
 
 
 Typically a single Server accepts WebSocket connections from many agents. Agents
-are identified by self-assigned globally unique instance identifiers (or
-instance_uid for short). The instance_uid is recorded in each message sent from
-the Agent to the Server and from the Server to the Agent.
+are identified by self-assigned or server-assigned globally unique instance
+identifiers (or instance_uid for short). The instance_uid is recorded in each
+message sent from the Agent to the Server and from the Server to the Agent.
 
 The default URL path for the initial WebSocket's HTTP connection is /v1/opamp.
 The URL path MAY be configurable on the Agent and on the Server.
@@ -159,6 +159,7 @@ message AgentToServer {
     AgentAddonStatuses addon_statuses = 3;
     AgentInstallStatus agent_install_status = 4;
     AgentDisconnect agent_disconnect = 5;
+    AgentToServerFlags flags = 6;
 }
 ```
 
@@ -175,6 +176,9 @@ created by other Agents. The instance_uid SHOULD remain unchanged for the
 lifetime of the agent process. The recommended format for the instance_uid is
 [ULID](https://github.com/ulid/spec).
 
+In case the Agent wants to use an identifier generated by the Server, the field
+SHOULD be set with a temporary value and RequestInstanceUid flag MUST be set.
+
 #### status_report
 
 The status of the Agent. MUST be set in the first AgentToServer message that the
@@ -199,6 +203,23 @@ the last AgentToServer message.
 AgentDisconnect MUST be set in the last AgentToServer message sent from the
 agent to the server.
 
+#### flags
+
+
+Bit flags as defined by AgentToServerFlags bit masks.
+
+```protobuf
+enum AgentToServerFlags {
+    FlagsUnspecified = 0;
+
+    // Flags is a bit mask. Values below define individual bits.
+
+    // The agent requests server go generate a new instance_uid, which will
+    // be sent back in ServerToAgent message
+    RequestInstanceUid     = 0x00000001;
+}
+```
+
 
 ## ServerToAgent Message
 
@@ -248,7 +269,8 @@ message ServerToAgent {
     AgentPackageAvailable agent_package_available = 6;
     Flags flags = 7;
     ServerCapabilities capabilities = 8;
-    ServerToAgentCommand command = 9;
+    AgentIdentification agent_identification = 9;
+    ServerToAgentCommand command = 10;
 }
 ```
 
@@ -261,6 +283,10 @@ is multiplexed into one WebSocket connection (for example when a terminating
 proxy is used) the instance_uid field allows to distinguish which Agent the
 ServerToAgent message is addressed to.
 
+Note: the value can be overriden by server by sending a new one in the
+AgentIdentification field. When this happens then Agent MUST update its
+instance_uid to the value provided and use it for all further communication.
+
 #### error_response
 
 error_response is set if the Server wants to indicate that something went wrong
@@ -358,6 +384,19 @@ enum ServerCapabilities {
 }
 ```
 
+
+#### agent_identification
+
+Properties related to identification of the agent, which can be overriden by the
+server if needed. When new_instance_uid is set, Agent MUST update instance_uid
+to the value provided and use it for all further communication.
+
+```protobuf
+message AgentIdentification {
+  string new_instance_uid = 1;
+}
+```
+
 #### command
 
 This field is set when the server wants the agent to
@@ -366,8 +405,6 @@ besides instance_uid or capabilities. All other fields will be ignored and the
 agent will execute the command. See [ServerToAgentCommand Message](#servertoagentcommand-message)
 for details.
 
-
-
 <h2 id="servererrorresponse-message">ServerErrorResponse Message</h2>
 
 
@@ -390,6 +427,7 @@ message ServerErrorResponse {
 ```
 
 
+
 <h4 id="type">type</h4>
 
 
@@ -1998,6 +2036,7 @@ The message has the following structure:
 message DownloadableFile {
     string download_url = 1;
     bytes content_hash = 2;
+    bytes signature = 3;
 }
 ```
 
@@ -2012,6 +2051,14 @@ downloads.
 The hash of the file content. Can be used by the Agent to verify that the file
 was downloaded correctly.
 
+#### signature
+
+Optional signature of the file content. Can be used by the Agent to verify the
+authenticity of the downloaded file, for example can be the 
+[detached GPG signature](https://www.gnupg.org/gph/en/manual/x135.html#AEN160).
+The exact signing and verification method is Agent specific. See 
+[Code Signing](#code-signing) for recommendations.
+
 <h2 id="agent-package-updates">Agent Package Updates</h2>
 
 Agent package is a downloadable file. The package can be downloaded by the Agent
@@ -2170,10 +2217,10 @@ The Server MAY disconnect or deny serving requests if it detects that the same
 Agent instance has more than one simultaneous connection or if multiple Agent
 instances are using the same instance_uid.
 
-Open Question: does the Server need to actively detect duplicate instance_uids,
-which may happen due to Agents using bad UID generators which create globally
-non-unique UIDs or for example because of cloning of the VMs where the Agent
-runs?
+The Server SHOULD detect duplicate instance_uids (which may happen for example
+when Agents are using bad UID generators or due to cloning of the VMs where the
+Agent runs). When a duplicate instance_uid is detected, Server SHOULD generate
+a new instance_uid, and send it as new_instance_uid value of AgentIdentification.
 
 <h2 id="authentication">Authentication</h2>
 
@@ -2349,7 +2396,7 @@ these restrictions by sending a remote config from the Server to the agent.
 It is recommended that remote configuration capabilities are not enabled in the
 Agent by default. The capabilities should be opt-in by the user.
 
-<h2 id="code-signing">Code Signing</h2>
+## Code Signing
 
 
 Any executable code that is part of an addon or agent package should be signed
@@ -2363,6 +2410,10 @@ recommend the following:
   agent specific and is outside the concerns of the OpAMP specification.
 * The Agent SHOULD verify executable code in downloaded files to ensure the code
   signature is valid.
+* The downloadable code can be signed with the signature included in the file content or 
+  have a detached signature recorded in the DownloadableFile
+  message's [signature](#signature) field. Detached signatures may be used for example
+  with [GPG signing](https://www.gnupg.org/gph/en/manual/x135.html#AEN160).
 * If Certificate Authority is used for code signing it is recommended that the
   Certificate Authority and its private key is not co-located with the OpAMP
   Server, so that a compromised Server cannot sign malicious code.
@@ -2472,9 +2523,9 @@ TBD
 * ~~Do we need the sequence_num concept?~~ Deleted for now, not necessary for
   current feature set, but may need to be restored for other features (e.g.
   custom "extensions").
-* Does the Server need to actively detect duplicate instance_uids, which may
+* ~~Does the Server need to actively detect duplicate instance_uids, which may
   happen due to Agents using bad UID generators which create globally non-unique
-  UIDs?
+  UIDs?~~ Added.
 * ~~Do we need to split the AddonStatus and AgentStatus from the general
   StatusReport?~~ Yes, splitted.
 * Does WebSocket frame compression work for us or do we need our own mechanism?