Skip to content

Latest commit

 

History

History
72 lines (48 loc) · 3.94 KB

icrc_29_window_post_message_transport.md

File metadata and controls

72 lines (48 loc) · 3.94 KB
Raw

ICRC-29: Window Post Message Transport for ICRC-25

Status
Draft

Summary

This standard defines a transport channel to send ICRC-25 messages from a relying party to a signer. The transport channel is based on the window.postMessage API.

Terminology

  • signer: A service that manages a user's keys and can sign and perform canister calls on their behalf.
  • relying party: A service that wants to request calls on a specific canister.

Trust Assumption

For this standard to represent an ICRC-25 compliant transport channel, the following assumptions must hold:

  • The user's machine is not compromised. In particular, the browser must deliver messages unchanged and represent the origin of the different parties correctly.
  • DNS entries are not compromised. The user's machine must be able to resolve the domain names of the relying party and signer correctly.

Establishing a Communication Channel

A window.postMessage communication channel is initiated by the relying party. The relying party opens a new window and polls repeatedly for the signer to reply with a message indicating that it is ready for interactions. The message sent by the relaying party is a JSON-RPC 2.0 call with method icrc29_status and no parameters:

{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "icrc29_status"
}

The signer should reply with a message indicating that it is ready to receive additional messages:

{
    "jsonrpc": "2.0",
    "id": "1",
    "result": "ready"
}

Note: The relying party should send icrc29_status messages in short intervals. It is expected that some of the messages will be lost due to being sent before the signer is ready.

After the "result": "ready" response has been received, the relying party can send ICRC-25 messages to the signer using the window.postMessage API.

Authentication

  • The relying party must authenticate the signer by the origin of the window that it opens.
  • The signer must authenticate the relying party by the origin property of the message event that it received.

Sending Messages

Messages are sent by calling window.postMessage on the signer window, or the window.opener respectively. When sending messages, the targetOrigin parameter must be set to the origin of the signer or relying party window.

The relying party may close the signer window in between interactions. If the relying party wants to continue a session after having closed the window, it must again go through the process of establishing a communication channel.

After sending a message, the relying party should wait for the signer to send a response before closing the window. If the window is closed before the signer has sent a response, the relying party must not make any assumptions about the state of the request.

Error Handling

Unexpectedly Closed Window

If the signer window is closed unexpectedly, the relying party should handle this as if it had received a NOT_GRANTED error. Closing the window does not end the session (see ICRC-25 session), and the relying party can open a new window and continue the session.

Invalid Messages

If either party receives malformed, unexpected, or otherwise invalid messages, it should ignore them.