SpecifAI portal embedding

Usage: open the SpecifAI portal (or another supported 3rd party portal) in another tab/window. Login and copy/paste a bearer token from one of the requests and paste it below. Make sure you copy a recent token (one that is not already expired and a token for the correct portal, staging or production). The application should load within a second or two. Check message log to see the JSON RPC messages receive from the child frame.

JSON RPC messages:

PROTOCOL DOCUMENTATION

High level overview of the embedding setup. The host frame and the child iframe containing the SpecifAI portal communicate via a standard MessageChannel object.

                    flowchart TB
                        subgraph ide1 [Host frame]
                        A@{ shape: sm-circ }
                        B[SpecifAI Portal]
                        A<-- JSON RPC over MessageChannel -->B
                    end

Via the message channel JSON RPC protocol messages are exchanged. The protocol DTOs are described below. The host frame should initialize the message channel by posting an "init" message to the client iframe containing one side (port) of the message channel:

iframe.contentWindow.postMessage("init", "*", [channel.port2]);

Child to Host

The child iframe, containing the SpecifAI portal, will send the following JSON RPC requests to the parent frame:

get-auth-token
This is sent whenever the portal needs a authentication token. The parent frame should respond with a valid JSON RPC response containing:
```
{ "token": "JWT" }
```

The child frame will send the following JSON RPC notifications to the parent frame:

authentication-state-changed
This is sent when the authentication state changes. The payload contains the current state: unauthenticated, authenticating, provisioning, authenticated.
user-changed
This is sent when the user is authenticated. The payload and contains the SpecifAI portal user details.

Host to child

Currently none, but can be extended to support requests such as "listDashboards", "openDashboard".

Authentication flow

The following sequence diagram show the authentication process the occurs behind the scenes.

                    sequenceDiagram
                        actor A as User
                        participant B as Host Application
                        participant C as Host Authencation server API
                        participant D as SpecifAI IFrame
                        participant E as SpecifAI API
                        A->>B: Login to host application
                        B->>C: Authenticate user
                        C-->>B: User authenticated (tokens returned)
                        C-->>B: 3rd party tokens
                        B->>D: Load SpecifAI IFrame with MessageChannel
                        D-->>B: Display SpecifAI loading screen
                        D->>B: Get token (JSON RPC)
                        B-->>D: Tokens returned
                        D->>E: Exchange 3rd party token for SpecifAI token
                        activate E
                        E->>C: GET https://3rd.party/oauth?token=ey...
                        activate C
                        C->>C: Validate received token
                        C-->>E: Return user details and permissions
                        deactivate C
                        E-->>D: Return provisioning user
                        E->>E: Provision user
                        D->>E: Exchange 3rd party token for SpecifAI token
                        E-->>D: Return provisioning user
                        E->>E: Provision user access
                        D->>E: Exchange 3rd party token for SpecifAI token
                        E-->>D: Return SpecifAI token
                        deactivate E
                        D-->>B: Display SpecifAI portal
                        D->>E: Refresh token
                        E-->>D: Refreshed tokens