Merge branch 'main' into DOTNET-FDC3-signatures

.github/ISSUE_TEMPLATE/standard-wg-meeting.md

@@ -43,7 +43,7 @@ Thursday DD MMM yyyy - 10am (US eastern timezone EDT/EST) / 3pm (London, GMT/BST
 
  Please click the following links at the start of the meeting if you have not done so previously.
 
- - [View the CSL](https://raw.githubusercontent.com/finos/FDC3/main/LICENSE)
+ - [View the CSL](https://raw.githubusercontent.com/finos/FDC3/main/LICENSE.md)
  - [View the GOVERNANCE of the Project](https://github.com/finos/FDC3/blob/main/GOVERNANCE.md)
  - [Click here to start a PR](https://github.com/finos/FDC3/edit/main/NOTICES.md). 
    - Edit the page to add your details.

.github/workflows/cve-scanning.yml

@@ -2,20 +2,21 @@ name: Node.js CVE Scanning
 
 on:
   pull_request:
+    types: [opened, reopened, synchronize, ready_for_review]
     paths:
       - 'package.json'
       - 'toolbox/fdc3-workbench/package.json'
       - '.github/workflows/cve-scanning.yml'
       - 'website/package.json'
-  push:
-    paths:
-      - 'package.json'
-      - 'toolbox/fdc3-workbench/package.json'
-      - '.github/workflows/cve-scanning.yml'
-      - 'website/package.json'
-    schedule:
-      # Run every day at 5am and 5pm
-      - cron: '0 5,17 * * *'
+  # push:
+  #   paths:
+  #     - 'package.json'
+  #     - 'toolbox/fdc3-workbench/package.json'
+  #     - '.github/workflows/cve-scanning.yml'
+  #     - 'website/package.json'
+  schedule:
+    # Run every day at 5am and 5pm
+    - cron: '0 5,17 * * *'
 
 jobs:
   build:

.github/workflows/scorecard.yml

@@ -0,0 +1,74 @@
+# This workflow uses actions that are not certified by GitHub. They are provided
+# by a third-party and are governed by separate terms of service, privacy
+# policy, and support documentation.
+
+name: Scorecard supply-chain security
+on:
+  # For Branch-Protection check. Only the default branch is supported. See
+  # https://github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection
+  branch_protection_rule:
+  # To guarantee Maintained check is occasionally updated. See
+  # https://github.com/ossf/scorecard/blob/main/docs/checks.md#maintained
+  schedule:
+    # “At 17:05 on Friday”
+    - cron: '5 17 * * 5'
+  push:
+    branches: [ "main" ]
+
+# Declare default permissions as read only.
+permissions: read-all
+
+jobs:
+  analysis:
+    name: Scorecard analysis
+    runs-on: ubuntu-latest
+    permissions:
+      # Needed to upload the results to code-scanning dashboard.
+      security-events: write
+      # Needed to publish results and get a badge (see publish_results below).
+      id-token: write
+      # Uncomment the permissions below if installing in a private repository.
+      # contents: read
+      # actions: read
+
+    steps:
+      - name: "Checkout code"
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        with:
+          persist-credentials: false
+
+      - name: "Run analysis"
+        uses: ossf/scorecard-action@0864cf19026789058feabb7e87baa5f140aac736 # v2.3.1
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          # (Optional) "write" PAT token. Uncomment the `repo_token` line below if:
+          # - you want to enable the Branch-Protection check on a *public* repository, or
+          # - you are installing Scorecard on a *private* repository
+          # To create the PAT, follow the steps in https://github.com/ossf/scorecard-action?tab=readme-ov-file#authentication-with-fine-grained-pat-optional.
+          repo_token: ${{ secrets.SCORECARD_TOKEN }}
+
+          # Public repositories:
+          #   - Publish results to OpenSSF REST API for easy access by consumers
+          #   - Allows the repository to include the Scorecard badge.
+          #   - See https://github.com/ossf/scorecard-action#publishing-results.
+          # For private repositories:
+          #   - `publish_results` will always be set to `false`, regardless
+          #     of the value entered here.
+          publish_results: false
+
+      # Upload the results as artifacts (optional). Commenting out will disable uploads of run results in SARIF
+      # format to the repository Actions tab.
+      - name: "Upload artifact"
+        uses: actions/upload-artifact@97a0fba1372883ab732affbe8f94b823f91727db # v3.pre.node20
+        with:
+          name: SARIF file
+          path: results.sarif
+          retention-days: 5
+
+      # Upload the results to GitHub's code scanning dashboard (optional).
+      # Commenting out will disable upload of results to your repo's Code Scanning dashboard
+      - name: "Upload to code-scanning"
+        uses: github/codeql-action/upload-sarif@1b1aada464948af03b950897e5eb522f92603cc2 # v3.24.9
+        with:
+          sarif_file: results.sarif

.github/workflows/semgrep.yml

@@ -1,6 +1,11 @@
 name: Static code analysis
 
-on: [push, pull_request]
+on:
+  pull_request:
+    types: [opened, reopened, synchronize, ready_for_review]
+  schedule:
+    # Run every day at 5am and 5pm
+    - cron: '0 5,17 * * *'
 
 jobs:
   semgrep:

CHANGELOG.md

@@ -9,6 +9,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 ### Added
 
 * Added clarification that `id` field values SHOULD always be strings to context schema definition (a restriction that can't easily be represented in the generated types). ([#1149](https://github.com/finos/FDC3/pull/1149))
+* Added requirement that Standard versions SHOULD avoid the use unions in context and API definitions wherever possible as these can be hard 
+ to replicate and MUST avoid unions of primitive types as these can be impossible to replicate in other languages. ([#120](https://github.com/finos/FDC3/pull/1200))
 
 ### Changed
 

docs/agent-bridging/ref/findIntentsByContext.md

@@ -6,7 +6,7 @@ title: findIntentsByContext
 
 Desktop Agent bridging message exchange for a `findIntent` API call on the [`DesktopAgent`](../../api/ref/DesktopAgent). Generated by API call:
 
-- [`findIntentsByContext(context: Context): Promise<Array<AppIntent>>`](../../api/ref/DesktopAgent#findintentsbycontext)
+- [`findIntentsByContext(context: Context, resultType?: string): Promise<Array<AppIntent>>`](../../api/ref/DesktopAgent#findintentsbycontext)
 
 [Message Exchange Type](../spec#individual-message-exchanges): **Request Response (collated)**
 
@@ -57,7 +57,8 @@ Outward message to the DAB:
 {
     "type": "findIntentsByContextRequest",
     "payload": {
-        "context": {/*contextObj*/}
+        "context": {/*contextObj*/},
+        "resultType": "fdc3.instrument"
     },
     "meta": {
         "requestUuid": "<requestUuid>",
@@ -78,7 +79,8 @@ The DAB fills in the `source.desktopAgent` field and forwards the request to the
 {
     "type": "findIntentsByContextRequest",
     "payload": {
-        "context": {/*contextObj*/}
+        "context": {/*contextObj*/},
+        "resultType": "fdc3.instrument"
     },
     "meta": {
         "requestUuid": "<requestUuid>",

docs/api/ref/DesktopAgent.md

@@ -47,6 +47,9 @@ interface DesktopAgent {
   getCurrentChannel() : Promise<Channel | null>;
   leaveCurrentChannel() : Promise<void>;
 
+  // non-context events 
+  addEventListener(type: FDC3EventType  | null, handler: EventHandler): Promise<Listener>;
+
   //implementation info
   getInfo(): Promise<ImplementationMetadata>;
 
@@ -174,6 +177,30 @@ var contactListener = await _desktopAgent.AddContextListener<Contact>("fdc3.cont
 - [`Context`](Types#context)
 - [`ContextHandler`](Types#contexthandler)
 
+### `addEventListener`
+```ts
+addEventListener(type: FDC3EventType  | null, handler: EventHandler): Promise<Listener>;
+```
+
+Registers a handler for non-context and non-intent events from the Desktop Agent. If the consumer is only interested in an event of a particular type, they can specify that type. If the consumer is able to receive events of any type or will inspect types received, then they can pass `null` as the `type` parameter to receive all event types.
+
+Whenever the handler function is called it will be passed an event object with details related to the event.
+
+**Examples:**
+
+```js
+// any event type
+const listener = await fdc3.addEventListener(null, event => { ... });
+
+// listener for a specific event type that logs its details
+const userChannelChangedListener = await fdc3.addEventListener(FDC3EventType.USER_CHANNEL_CHANGED, event => { 
+  console.log(`Received event ${event.type}\n\tDetails: ${event.details}`);
+  //do something else with the event
+});
+````
+
+
+
 ### `addIntentListener`
 
 <Tabs groupId="lang">

docs/api/ref/Events.md

@@ -0,0 +1,59 @@
+---
+title: Events
+---
+
+In addition to intent and context events, the FDC3 API may be used to listen for other types of events via the `addEventListener()` function.
+
+## `EventHandler`
+
+```ts
+type EventHandler = (event: FDC3Event) => void;
+```
+
+Describes a callback that handles non-context and non-intent events. Provides the details of the event. 
+
+Used when attaching listeners to events. 
+
+**See also:**
+- [`DesktopAgent.addEventListener`](DesktopAgent#addEventListener)
+- [`FDC3Event`](#fdc3event)
+
+## `FDC3EventType`
+```ts
+enum FDC3EventType {
+  USER_CHANNEL_CHANGED = "USER_CHANNEL_CHANGED"
+}
+```
+
+Enumeration defining the types of (non-context and non-intent) events that may be received via the FDC3 API's `addEventListener` function. 
+
+**See also:**
+- [`DesktopAgent.addEventListener`](DesktopAgent#addEventListener)
+
+## `FDC3Event`
+
+```ts
+interface FDC3Event {
+  readonly type: FDC3EventType;
+  readonly details: any;
+}
+```
+
+Type representing the format of event objects that may be received via the FDC3 API's `addEventListener` function. Will always include both `type` and `details`, which describe type of the event and any additional details respectively.
+
+**See also:**
+- [`DesktopAgent.addEventListener`](DesktopAgent#addEventListener)
+- [`FDC3EventType`](#fdc3eventtype)
+
+
+### `FDC3ChannelChangedEvent`
+```ts
+interface FDC3ChannelChangedEvent extends FDC3Event {
+  readonly type: FDC3EventType.USER_CHANNEL_CHANGED;
+  readonly details: {
+    currentChannelId: string | null
+  };
+}
+```
+
+Type representing the format of USER_CHANNEL_CHANGED events. The identity of the channel joined is provided as `details.currentChannelId`, which will be `null` if the app is no longer joined to any channel.

docs/api/spec.md

@@ -51,6 +51,12 @@ The FDC3 API specification consists of interfaces.  It is expected that each Des
 
 Other interfaces defined in the spec are not critical to define as concrete types.  Rather, the Desktop Agent should expect to have objects of the interface shape passed into or out of their library.
 
+### Implementation language
+
+FDC3 and the Desktop Agent API it defines are intended to be independent of particular programming languages and platforms and hence the original definitions, produced in TypeScript, may be translated into other languages. However, this also places limitations on the API definitions as they need to be widely implementable in other languages.
+
+Specifically, the use of ['unions'](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#union-types) of primitive values in API type and metadata objects, or function parameters SHOULD be avoided as they often cannot be replicated in other languages. Unions of more complex types (such as specific [Context](ref/Context) Types) may be used where a suitable interface is available or can be created to allow the required polymorphism in languages other than TypeScript.
+
 For implementation details relating to particular languages, and how to access the API in those languages, please see [Supported Platforms](supported-platforms).
 
 ### Standards vs. Implementation
@@ -84,8 +90,8 @@ There is currently no method of discovering all the apps supported by a Desktop
 
 An FDC3 Standard compliant Desktop Agent implementation **MUST**:
 
-- Provide the FDC3 API to web applications via a global accessible as [`window.fdc3`](#api-access).
-- Provide a global [`fdc3Ready`](#api-access) event that is fired when the API is ready for use.
+- Provide the FDC3 API to web applications via a global accessible as [`window.fdc3`](support-platforms#web).
+- Provide a global [`fdc3Ready`](support-platforms#web) event to web applications that is fired when the API is ready for use.
 - Provide a method of resolving ambiguous intents (i.e. those that might be resolved by multiple applications) or unspecified intents (calls to `raiseIntentForContext` that return multiple options), such as a resolver UI.
   - Intent resolution MUST take into account any specified input or return context types
   - Requests for resolution to apps returning a channel MUST include any apps that are registered as returning a channel with a specific type.
@@ -94,6 +100,7 @@ An FDC3 Standard compliant Desktop Agent implementation **MUST**:
 - Include implementations of the following [Desktop Agent](ref/DesktopAgent) API functions, as defined in this Standard:
   - [`addContextListener`](ref/DesktopAgent#addcontextlistener)
   - [`addIntentListener`](ref/DesktopAgent#addintentlistener)
+  - [`addEventListener`](ref/DesktopAgent#addEventListener)
   - [`broadcast`](ref/DesktopAgent#broadcast)
   - [`createPrivateChannel`](ref/DesktopAgent#createprivatechannel)
   - [`findInstances`](ref/DesktopAgent#findinstances)

docs/context/spec.md

@@ -62,7 +62,7 @@ interface Context {
 
 or in JSON Schema as:
 
-```JSON
+```json
 {
     "$schema": "http://json-schema.org/draft-07/schema#",
     "$id": "https://fdc3.finos.org/schemas/next/context/context.schema.json",
@@ -104,6 +104,39 @@ It may be as simple as adding an optional `$version` property to types, but it c
 
 This Standard defines a number of conventions for the fields of context types that all context objects SHOULD adhere to in order to reduce or prevent competing conventions from being established in both standardized types and proprietary types created by app developers.
 
+#### Avoid union types / composition of primitive types
+
+Both Typescript and JSON Schema allow for a type of polymorphism in types and interfaces that is hard to represent in other languages: allowing the type of a variable to be a ['union'](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#union-types) of other, unrelated types. E.g.: in TypeScript
+
+```ts
+type Example = SomeOtherType | YetAnotherType;
+```
+
+Similar constructs are allowed in JSON Schema by [combining or composing schemas](https://json-schema.org/understanding-json-schema/reference/combining) using the `anyOf` or `oneOf` keywords to specify that a value can take the form defined in one-or-more or one-of-several sub-schemas.
+
+```json
+"recipients": {
+    "title": "Email Recipients",
+    "description": "One or more recipients for the email.",
+    "oneOf": [
+        {
+            "$ref": "contact.schema.json#"
+        },
+        {
+            "$ref": "contactList.schema.json#"
+        }
+    ]
+}
+```
+
+However, other languages can be less flexible. In most languages, polymorphism of object types is possible via the implementation and/or extension of an interface (for example all context types are derived from the [Context](ref/Context) schema, which can be modelled as an interface). However, this approach is not possible if one of the types in the union is a primitive, meaning it's not a class and can't be modified to implement an interface, e.g.:
+
+```ts
+type Example2 = SomeOtherType | number;
+```
+
+Hence, to ensure that FDC3 context objects are implementable in other languages context schemas MUST NOT use `anyOf`/`oneOf` compositions of primitive types in JSON schema (and, hence, unions of primitive types in TypeScript) and SHOULD avoid compositions of Object types unless a concept that can be defined as an interface (such as [Context](ref/Context)) is available.
+
 #### Identifiers
 
 An `id` field with type `object` is defined in the base [fdc3.context](ref/Context) type, from which all other context objects are derived, and SHOULD be used to encapsulate identifiers. Specific context types may define subfields for specific identifiers as needed.

jest.config.js

@@ -2,12 +2,10 @@
 module.exports = {
     moduleFileExtensions: ["js", "ts"],
     globals: {
-        "ts-jest": {
-            isolatedModules: true
-        }
+
     },
     transform: {
-        "^.+\\.ts?$": "ts-jest"
+        "^.+\\.ts?$": ["ts-jest", { isolatedModules: true }]
     },
     testRegex: ".+\\.test\\.ts?$",
     testEnvironment: "jsdom",