Implementing ContextMetadata support in fdc3-web-impl and adding getCurrentContextWithMetadata function

Author: kriswest

packages/fdc3-agent-proxy/src/channels/DefaultChannel.ts

@@ -1,5 +1,7 @@
 import {
   ContextHandler,
+  ContextWithMetadata,
+  ContextMetadata,
   DisplayMetadata,
   Listener,
   Channel,
@@ -78,6 +80,40 @@ export class DefaultChannel implements Channel {
     return response.payload.context ?? null;
   }
 
+  /**
+   * Retrieves the current context along with its metadata.
+   * Used by the proxy to deliver metadata to context listeners when replaying
+   * context after a channel change.
+   */
+  async getCurrentContextWithMetadata(contextType?: string): Promise<ContextWithMetadata | null> {
+    const request: GetCurrentContextRequest = {
+      meta: this.messaging.createMeta(),
+      payload: {
+        channelId: this.id,
+        contextType: contextType ?? null,
+      },
+      type: 'getCurrentContextRequest',
+    };
+    const response = await this.messaging.exchange<GetCurrentContextResponse>(
+      request,
+      'getCurrentContextResponse',
+      this.messageExchangeTimeout
+    );
+
+    const context = response.payload.context;
+    if (context) {
+      const metadata: ContextMetadata = {
+        source: response.payload.metadata?.source ?? { appId: 'unknown' },
+        timestamp: response.payload.metadata?.timestamp ?? response.meta.timestamp,
+        traceId: response.payload.metadata?.traceId ?? '',
+        signature: response.payload.metadata?.signature,
+        custom: response.payload.metadata?.custom,
+      };
+      return { context, metadata };
+    }
+    return null;
+  }
+
   async addContextListener(
     contextTypeOrHandler: string | null | ContextHandler,
     handler?: ContextHandler

packages/fdc3-agent-proxy/src/channels/DefaultChannelSupport.ts

@@ -295,9 +295,10 @@ export class DefaultChannelSupport implements ChannelSupport, Connectable {
 
       async changeChannel(): Promise<void> {
         if (this.container.currentChannel != null) {
-          const context = await this.container.currentChannel?.getCurrentContext(this.contextType ?? undefined);
-          if (context) {
-            this.handler(context);
+          const channel = this.container.currentChannel as DefaultChannel;
+          const result = await channel.getCurrentContextWithMetadata(this.contextType ?? undefined);
+          if (result) {
+            this.handler(result.context, result.metadata);
           }
         }
       }

packages/fdc3-agent-proxy/src/listeners/DefaultContextListener.ts

@@ -1,10 +1,9 @@
-import { ContextHandler, DesktopAgentProvidableContextMetadata } from '@finos/fdc3-standard';
+import { ContextHandler, ContextMetadata } from '@finos/fdc3-standard';
 import { Messaging } from '../Messaging.js';
 import { AbstractListener } from './AbstractListener.js';
 import { AddContextListenerRequest, BroadcastEvent } from '@finos/fdc3-schema/dist/generated/api/BrowserTypes.js';
 import { RegisterableListener } from './RegisterableListener.js';
 
-
 export class DefaultContextListener
   extends AbstractListener<ContextHandler, AddContextListenerRequest>
   implements RegisterableListener
@@ -45,10 +44,12 @@ export class DefaultContextListener
   }
 
   action(m: BroadcastEvent): void {
-    const metadata: DesktopAgentProvidableContextMetadata = {
+    const metadata: ContextMetadata = {
       source: m.payload.metadata?.source,
       timestamp: m.payload.metadata?.timestamp ?? m.meta.timestamp,
       traceId: m.payload.metadata?.traceId,
+      signature: m.payload.metadata?.signature,
+      custom: m.payload.metadata?.custom,
     };
     this.handler(m.payload.context, metadata);
   }

packages/fdc3-agent-proxy/src/listeners/DefaultIntentListener.ts

@@ -37,6 +37,8 @@ export class DefaultIntentListener extends AbstractListener<IntentHandler, AddIn
       source: m.payload.metadata?.source as AppIdentifier,
       timestamp: m.payload.metadata?.timestamp ?? m.meta.timestamp,
       traceId: m.payload.metadata?.traceId ?? v4(),
+      signature: m.payload.metadata?.signature,
+      custom: m.payload.metadata?.custom,
     });
 
     this.handleIntentResult(done, m);

packages/fdc3-schema/generated/api/BrowserTypes.ts

@@ -1264,6 +1264,11 @@ export interface ContextMetadata {
    * standardized.
    */
   custom?: { [key: string]: any };
+  /**
+   * A cryptographic signature that can be used to verify the authenticity and integrity of
+   * the context or intent message.
+   */
+  signature?: string;
   /**
    * Identifier for the app instance that sent the context and/or intent.
    */
@@ -1327,6 +1332,7 @@ export interface BroadcastRequestPayload {
  */
 export interface AppProvidableContextMetadata {
   custom?: { [key: string]: any };
+  signature?: string;
   traceId?: string;
 }
 
@@ -2732,6 +2738,13 @@ export interface GetCurrentContextResponsePayload {
    * or `null` if none was available in the channel.
    */
   context?: null | Context;
+  /**
+   * Metadata relating to the most recently broadcast context object, if available. This is
+   * not returned by the public getCurrentContext API but is used internally by the Desktop
+   * Agent proxy to deliver metadata to context listeners when replaying context after a
+   * channel change.
+   */
+  metadata?: ContextMetadata | null;
 }
 
 /**
@@ -5305,6 +5318,7 @@ const typeMap: any = {
   ContextMetadata: o(
     [
       { json: 'custom', js: 'custom', typ: u(undefined, m('any')) },
+      { json: 'signature', js: 'signature', typ: u(undefined, '') },
       { json: 'source', js: 'source', typ: r('AppIdentifier') },
       { json: 'timestamp', js: 'timestamp', typ: Date },
       { json: 'traceId', js: 'traceId', typ: '' },
@@ -5330,6 +5344,7 @@ const typeMap: any = {
   AppProvidableContextMetadata: o(
     [
       { json: 'custom', js: 'custom', typ: u(undefined, m('any')) },
+      { json: 'signature', js: 'signature', typ: u(undefined, '') },
       { json: 'traceId', js: 'traceId', typ: u(undefined, '') },
     ],
     false
@@ -5780,6 +5795,7 @@ const typeMap: any = {
     [
       { json: 'error', js: 'error', typ: u(undefined, r('PurpleError')) },
       { json: 'context', js: 'context', typ: u(undefined, u(null, r('Context'))) },
+      { json: 'metadata', js: 'metadata', typ: u(undefined, u(r('ContextMetadata'), null)) },
     ],
     false
   ),

packages/fdc3-schema/generated/bridging/BridgingTypes.ts

@@ -661,6 +661,7 @@ export interface Context {
  */
 export interface AppProvidableContextMetadata {
   custom?: { [key: string]: any };
+  signature?: string;
   traceId?: string;
 }
 
@@ -5126,6 +5127,7 @@ const typeMap: any = {
   AppProvidableContextMetadata: o(
     [
       { json: 'custom', js: 'custom', typ: u(undefined, m('any')) },
+      { json: 'signature', js: 'signature', typ: u(undefined, '') },
       { json: 'traceId', js: 'traceId', typ: u(undefined, '') },
     ],
     false

packages/fdc3-schema/schemas/api/api.schema.json

@@ -288,6 +288,11 @@
                     "title": "timestamp",
                     "description": "The timestamp when the context or intent was created, encoded according to [ISO 8601-1:2019](https://www.iso.org/standard/70907.html) with a timezone indicator."
                 },
+                "signature": {
+                    "type": "string",
+                    "title": "signature",
+                    "description": "A cryptographic signature that can be used to verify the authenticity and integrity of the context or intent message."
+                },
                 "custom": {
                     "type": "object",
                     "additionalProperties": true,
@@ -308,6 +313,7 @@
             "title": "App Providable Context Metadata",
             "properties": {
                 "traceId": {"$ref": "#/definitions/ContextMetadata/properties/traceId"},
+                "signature": {"$ref": "#/definitions/ContextMetadata/properties/signature"},
                 "custom": {"$ref": "#/definitions/ContextMetadata/properties/custom"}
             },
             "additionalProperties": false

packages/fdc3-schema/schemas/api/getCurrentContextResponse.schema.json

@@ -45,6 +45,14 @@
 						{ "$ref": "../context/context.schema.json" },
 						{ "type": "null" }
 					]
+				},
+				"metadata": {
+					"title": "Context Metadata",
+					"description": "Metadata relating to the most recently broadcast context object, if available. This is not returned by the public getCurrentContext API but is used internally by the Desktop Agent proxy to deliver metadata to context listeners when replaying context after a channel change.",
+					"oneOf": [
+						{ "$ref": "api.schema.json#/definitions/ContextMetadata" },
+						{ "type": "null" }
+					]
 				}
 			},
 			"required": [

packages/fdc3-standard/src/api/Channel.ts

@@ -4,7 +4,7 @@
  */
 
 import { Context } from '@finos/fdc3-context';
-import { ContextHandler } from './Types.js';
+import { ContextHandler, ContextWithMetadata } from './Types.js';
 import { DisplayMetadata } from './DisplayMetadata.js';
 import { Listener } from './Listener.js';
 import { EventHandler } from './Events.js';
@@ -68,6 +68,24 @@ export interface Channel {
    */
   getCurrentContext(contextType?: string): Promise<Context | null>;
 
+  /**
+   * Returns the most recent context that was broadcast on the channel, along
+   * with its associated metadata, or `null` if no matching context is found.
+   *
+   * When a `contextType` is provided, the most recent context matching the type
+   * will be returned. If no `contextType` is provided, the most recent context
+   * that was broadcast on the channel - regardless of type - will be returned.
+   *
+   * This function is similar to `getCurrentContext()` but additionally returns
+   * the `ContextMetadata` that was associated with the context when it was
+   * broadcast, allowing applications to access information such as the source
+   * app, timestamp, traceId, signature and any custom metadata.
+   *
+   * If getting the current context fails, the promise will be rejected with an
+   * `Error` with a `message` string from the `ChannelError` enumeration.
+   */
+  getCurrentContextWithMetadata(contextType?: string): Promise<ContextWithMetadata | null>;
+
   /**
    * Adds a listener for incoming contexts of the specified _context type_ whenever a broadcast happens on this channel.
    *

packages/fdc3-standard/src/api/ContextMetadata.ts

@@ -6,21 +6,12 @@
 import { AppIdentifier } from './AppIdentifier.js';
 
 /**
- * Metadata relating to a context or intent and context received through the
- * `addContextListener` and `addIntentListener` functions.
- *
- * @experimental Introduced in FDC3 2.0 and may be refined by further changes outside the normal FDC3 versioning policy.
- */
-export interface ContextMetadata {
-  /** Identifier for the app instance that sent the context and/or intent.
-   *
-   *  @experimental
-   */
-  readonly source: AppIdentifier;
-}
-
+ * Metadata that may be provided by an App when calling broadcast, open or
+ * raiseIntent functions, to be passed onto receiving apps.
+ * */
 export interface AppProvidableContextMetadata {
-  /** A unique identifier for tracing the flow of context or intent messages across applications.
+  /** A unique identifier for tracing the flow of context or intent messages
+   * across applications.
    * This is useful for debugging and monitoring message flow in complex interop scenarios.
    * If a traceId is provided by the app, the Desktop Agent SHOULD forward it.
    * If no traceId is provided by the app, the Desktop Agent SHOULD generate a new one.
@@ -31,24 +22,24 @@ export interface AppProvidableContextMetadata {
    * of the context or intent message. This is useful for security-sensitive applications.
    * If a signature is provided by an app, it MAY be verified by the Desktop Agent. */
   signature?: string;
+
+  /**
+   * Custom metadata that can be used to provide additional information about
+   * the context or intent. This allows for individuals to use metadata fields
+   * that have yet to be standardized.
+   */
+  custom?: Record<string, any>;
 }
 
-export interface DesktopAgentProvidableContextMetadata {
+/**
+ * Metadata relating to a context or intent and context received through the
+ * `addContextListener` and `addIntentListener` functions.
+ */
+export interface ContextMetadata extends AppProvidableContextMetadata {
   /** The timestamp when the context was broadcast or the intent was raised.
    * This can be used for debugging, auditing, or ordering events. */
-  timestamp?: Date;
+  timestamp: Date;
 
   /** The identifier of the app instance that originated the context or intent. */
-  source?: AppIdentifier;
-
-  /** A unique identifier for tracing the flow of context or intent messages across applications.
-   * This is useful for debugging and monitoring message flow in complex interop scenarios.
-   * If a traceId is provided by the app, the Desktop Agent SHOULD forward it.
-   * If no traceId is provided by the app, the Desktop Agent SHOULD generate a new one.
-   * */
-  traceId?: string;
-
-  /** A cryptographic signature that can be used to verify the authenticity and integrity
-   * of the context or intent message. This is useful for security-sensitive applications. */
-  signature?: string;
+  source: AppIdentifier;
 }