Allow an app to retrieve its own AppMetadata

[kriswest]

Enhancement Request

There are times when it may be useful for an application to be able to retrieve its own AppMetadata via the Desktop Agent API. An AppMetadata object encodes the Desktop Agent's name, appId and instance metadata for a particular app instance and can be used, for example, to target future intents at it.

Add a new required (MUST) API call for an app to retrieve its own metadata:

interface DesktopAgent {
  ...
  getMyAppMetadata(): Promise<AppMetadata>;
}

Use Case:

• see issue StartChat and SendChatMessage #574, the propose ChatRoomRef context doesn't work without a reference to the application that created the Chat room. Whilst the application can populate that returned context with its own name, that doesn't necessarily match the configured name or appId of the app as far as the desktop agent is concerned and can't be used to target subsequent intents at it.
• Require propagation of originating application identity on context/intent handlers #520 and Support propagation of originating application identity #569 propose propagation of AppMetadata with intents and context messages, while this should be done automatically by the Desktop Agent there may be times when an app wishes to notify another of its metadata within a context OR may be notified of the origination of message or request and need to recognise its own metadata.

[MichaelMCoates]

Just following up here:

• We brought up that we'd like to see real workflows of this API in use
• In relation to that, one of the proposed workflows (including app metadata as part of a context payload) raised the potential of spoofing
• Raised the question of "Who should be responsible for this decision-making/control, the applications themselves, or the Desktop Agent?"

[kriswest]

There are a few possible workflows that would require an app to be able to retrieve its own AppMetadata:

• An app wishes to open another instance of itself (e.g. open in new window) via fdc3.open. However, it doesn't know its own appId as it was configured in the appD by someone other than the developer. Hence, it needs to retrieve its own AppMetadata to know its configured appId.
• An app (and/or desktop owner) wishes to log activity of one or more instances of the application, including interactions between those instances. It requires its own appId and instanceId in order to do so and must retrieve the via the API.
• An app wishes to pass context to another instance of itself. It is able to retrieve the list of available instances via findInstances(), but needs to know its own AppMetadata to do so and its own AppMetadata.instanceId in order to eliminate itself from the list.
• A particular workflow passes through multiple applications and ends at the originating app. At each step, 'originating app metadata' is available (Require propagation of originating application identity on context/intent handlers #520 having been implemented) and is used for logging or otherwise accumulated. When the workflow ends back at the originating app it wishes to confirm that it originated the workflow, but it can't recognize its own metadata as it is unable to retrieve it.

These workflows primarily relate to utility functions, rather than security. I agree that we should not encourage situations where an app is required to add its own metadata to a context and to rely on that for security or access control. This should be clarified in the relevant documentation for any function added.

Raised the question of "Who should be responsible for this decision-making/control, the applications themselves, or the Desktop Agent?"

I assume this relates to #520 where it is proposed that the Desktop Agent be responsible for supplying the originating app metadata, which is more secure, but only if you trust the Desktop Agent implementation (which @bingenito pointed out can itself also be spoofed, although the facility would still be useful/appreciated). This issue essentially seeks to provide parity to the application, allowing it to know its own metadata (which #520 will expose to other apps).

[kriswest]

As discussed at the SWG meeting today, we'll proceed with an alternative proposal to implement this use-case, without increasing the surface area of the DesktopAgent API, by adding the app's own metadata to the ImplementationMetadata object returned by fdc3.getInfo().

I.e. update:

public interface ImplementationMetadata {
  fdc3Version: string;
  provider: string;
  providerVersion?: string;
} 

to

public interface ImplementationMetadata {
  fdc3Version: string;
  provider: string;
  providerVersion?: string;
  appMetadata: AppMetadata;
}