finos / FDC3

An open standard for the financial desktop.
https://fdc3.finos.org
Other
198 stars 125 forks source link

Support better identity validation in Preload Desktop Agents #1339

Open kriswest opened 2 months ago

kriswest commented 2 months ago

The FDC3 for the Web meeting spent some time discussing assumptions in FDC3 that are not correct and needed to be dealt with when working in a Web Browser. Specifically, the issue of the identity of an application running in a window, which can change through validation. The FDC3 specification does not address or deal with that anywhere. Rather, it is assumed that the Desktop Agent starts each app, using an AppD record (or similar config) that provides the details of its identity and other metadata, and that it never changes identity until closed.

Changes in identity are more likely in web browser-based Desktop Agents as the user could, for example, simply type in a new web address and navigate a window away. However, they are still possible in a container without a visible addressbar as a user might simply click on a link or button that navigates them to a new page (either as part of the design of a suite of apps or through a link embedded in content).

The FDC3 for Web proposal deals with such changes as the connection to the Desktop Agent is reestablished every time a refresh or navigation event occurs and identity is re-checked. However, there is no equivalent solution in Preload Desktop Agents. In FDC3 for the Web identity checks are handled as part of the connection messages, but there is no equivalent process in Preload Desktop Agents, which means we will likely need to add an API call to handle identity validation. That API call could be handled automatically by the getAgent() implementation. Further, it is currently based on the application's URL (or an identityUrl that the app specifies, who's origin MUST match the current app URL - which can be validated through browser APIs as it is sent with a postMessage) - the URL is already captured by getAgent() so if an app switches to use getAgent() (which is proposed to become the new recommendation for getting access to the API) then it may not need to supply any arguments or interact with that API call.

An API call for identity validation might look like:

/**
   * @experimental
   * Optional function, that can be used by getAgent() to validate app identity
   * in preload Desktop Agents. Apps should not call this function directly.
   *
   * See `getAgent` for instructions.
   *
   * `identityUrl` is used to identify an application and may be used to match
   * to an appD record known to the Desktop Agent. As applications may navigate
   * to different URLs (changing their path, search parameters or hash) during
   * normal use they may provide a URL to use to identify themselves. Preload 
   * Desktop Agents can usually determine the current URL of the window and 
   * MUST validate that it matches the origin of the `identityUrl`.
   * 
   * Instance identity should be determined by a preload Desktop agent
   * internally, without the need for an instanceUuid as used with Web Desktop Agents.
   *
   * In the event that instance identity cannot be validated, the Desktop Agent
   * MUST prevent further communication with the application.
   * 
   * This function is optional but recommended.
   */
  validateAppIdentity?({
    identityUrl
  }: {
    identityUrl: string;
  }): Promise<DesktopAgentDetails>;

Further, an identity validation procedure might be relevant to proposals from the Identity & Threat Modelling discussion group, which may decide later to enhance it with an async encryption approach (public/private key).

kriswest commented 2 months ago

Small additional use case: An identityValidation function might allow single page apps (from suites of apps) to change identity without navigation, switching intents they can resolve, instances they present as etc.