Skip to content

Aries RFC 0268: Unified DIDCOMM Deeplinking

Summary

A set of specifications for mobile agents to standardize around to provide better interoperable support for DIDCOMM compliant messages. Standards around the way agents intepret these encoded messages allow increased user choice when picking agents.

This RFC lists a series of standards which must be followed by an Aires compatible agent for it to be considered interoperable with other agents.

Motivation

As more and more mobile agents come to market, the user base for these wallets will become increasingly fragmented. As one of the core tennats of SSI is interoperability we want to ensure that messages passed to users from these wallets are in formats that any wallet can digest. We want to ensure that the onboarding experience for new users is as seemless and unified as possible.

Tutorial

Alice wants to invite Bob to connect with her. Alice sends Bob a invitation link generated by her Mobile Agent (a wallet provided by ACME Corp).

The invitation url takes the form of: "www.acmecorp.com/invite?d_m=XXXXX" where the text following the query parameter "d_m" is the base64url-encoded invitation.

Bob recieves this link and opens it on his phone. Since he doesn't have an Aires wallet, he gets directed to the webpage, "acmecorp.com/invite" where there's a list of wallets for each platform that he can choose and pick from. On the page is also the ACME Corp offical wallet.

Bob decides to download the ACME Corp wallet and clicks on the link again. Because the ACME Corp wallet registered 'www.acmecorp.com' as it's deeplink, Bob gets prompted to open it in the ACME Corp app.

Alice sends a similar invite to Charlie. Charlie uses a wallet distributed by Open Corp. Open Corp does not have the "acmecorp.com" URI registered as their deeplink, because they do not own that domain.

When Charlie lands on that page, along with the offer for wallets is a QR Code with the encoded invitation and a button that states "Open in App". This button launches the didcomm:// custom protocol, which is registered by ALL Aires compatible wallets (in the same way e-mail apps all register mailto: ).

Pressing the button prompts Charlie's phone to open the app that can handle didcomm://, which happens to be the wallet app by Open Corp.

In both instances, Alice does not need to worry about what wallet the counter party is using and can send didcomm messages with the assurance that the counter party will have a onboarding experience waiting for them even if they don't have a wallet already.

Reference

URI Registration

Each mobile agent should register their own URI to open in app. These URI's should point to a landing invitation page.

An example of such a URI page/invitation: "www.spaceman.id/invite?d_m=" In this case, if the recepient of this URL has an app that's registered Spaceman.id as it's domain (likely a wallet published by spaceman.id) then it will open the invation in app. If the recepient does not have the app installed, they'll have a page open on their mobile browser with suggestions for DIDCOMM compliant wallets.

Invitation Page

The Invitation page users land on must have a list of DIDCOMM compliant agents for each platform (iOS, Android). A list of these can be found here:

The Invitation page must also show the encoded message as a scannable QR code and have a button ("Open in App") to manually launch the didcomm:// protcol. The QR code helps interactions between web and mobile agent wallets.

The button to manually launch the didcomm:// protocol allows other Aires wallets on their phone to launch to handle the message, even if they haven't registered that specific URI. Alternatively you can use a library to automatically launch the didcomm:// prefix when the webpage is opened.

The Invitation page should also run a URL shortner service. This would help passing messages between services easily without needing to pass massive strings around. This also prevents polluting closed source properitary services with links.

There must exist a common prefix for mobile agents to register for DIDCOMM messages. This vastly improves interoperability between agents and messages, as they can be opened by any wallet. As the messages are all off the DIDCOMM family, we think the prefix that is best suited is didcomm://

All Mobile Agents should register didcomm:// as affilated with their app to both iOS and Android. This will enable users to be prompted to use their wallet when they recieve a DIDCOMM message.

Message Requirements

Proposed is a change to the query parameter usually used for the passing of the message from 'c_i' which stands for connection invite to the more inclusive 'd_m' which stands for DIDCOMM message.

Furthermore, messages must also be base64 encoded serialized jsons, stripped of any excess space and as small as possible.

Drawbacks

This puts extra work on wallet developers to ensure a good experience.

On iOS only one app can be registered to handle didcomm:// at a time; the first one to be installed will prevent others from using this custom scheme.

Rationale and alternatives

This allows each wallet to define their own invite page (or use an existing page provided by the community) while providing a common protocol scheme (didcomm://) for all applications.

If we don't do this, there's a chance that wallet applications become unable to communicate with each other effecively during the onboarding process, leading to fragmentation, much like in the IM world.

Prior Art

Unresolved Questions

Implementations

The following lists the implementations (if any) of this RFC. Please do a pull request to add your implementation. If the implementation is open source, include a link to the repo or to the implementation within the repo. Please be consistent in the "Name" field so that a mechanical processing of the RFCs can generate a list of all RFCs supported by an Aries implementation.

Implementation Notes.

Name / Link Implementation Notes