Adopt .well-known/did-configuration for Issuer and Verifier Web Servers

[OR13]

See comments below, the spec for this is being tracked:

https://github.com/decentralized-identity/well-known/tree/master/did-configuration

This ticket contains a lot of ideation, please refer to the spec ^.

We propose that the .well-known/did standard be used to exposing the DIDs used by this web server.

I don't see the spec for this anywhere... so we need that, or we will have to use a hack like:

HTTP GET http://example.com/.well-known/did

{
  "dids": ["did:ethr:fff...."],
  "registered_did_jwts": [...]
}

Where a registered_did_jwt is a JWS from a did listed in "dids" of a payload:

{
 "iss": "did:ethr:fff...",
 "sub": "did:ethr:fff...",
  "dif_authorized_credential_issuer_vc_v0": "http://example.com"
}

If this signature is valid, then the DID is a credential issuer for http://example.com

I'm making this all up, we should really have a standard for .well-known/did

[coder5876]

@awoie Does uPort have an implementation/spec for this?

[csuwildcat]

There was not yet a formal spec for this, but we had written down some strawman ideas here: https://hackmd.io/Xn4FAapEThu1fycJ9bY9OA

----- This is the content from that HackMD doc -----

Domain-to-DID Linkage

One common form of trust we would like to support is the ability of a DID to prove ownership of a DNS domain. There are a few possible options for doing this, but the following two are relatively straightforward to accomplish without any complex protocol code:

DNS URI Record

The URI record type is arguably the closest fit for declaring a DID relationship in a DNS Zone File. In talking with Markus, there was some exploration done in this area that participated in with a few folks from DNS working groups. You can read their proposal here: https://datatracker.ietf.org/doc/draft-mayrhofer-did-dns/?include_text=1

Here is an example of what they currently propose:

_did.example.net.  IN URI 100 10 "did:ion:1234abcd"

The group that worked on this proposal assumed that you would resolve the DID referenced in the URI Record and locate a matching domain in its DID Document, to create a two-way verification of the linkage. The issue with this approach is that validation based on inclusion of a domain entry in a DID Document forces a potentially significant amount of unnecessary data into the DID Document, consuming the DID network's scarce resources. Instead, I propose adding a signature to the URI record's DID value that allows an observer to prove the DID owner signed the matching domain string to authorize the association.

Here is an example of my proposed modification:

_did.example.net.  IN URI 100 10 "did:ion:1234abcd?sig=3Yj4De#key-1"

The signature is over the value of the domain name string specified in the URI record's Name string (at the start of the record, on the left), and the DID Document key descriptor ID of the key it was signed with.

Well-Known URI

Another option is to register a new /.well-known URI with IANA. Here is the current list of IANA-registered Well-Known URIs: https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml

We could register a URI of /.well-known/did, which could be a JSON file of the following format:

{
    "did:ion:1234abcd": {
        "key": "key-1",
        "signature": "3Yj4De..."
    },
    "did:ion:5678efgh": { ... }
}

[OR13]

is key-1 a key id matching a key in the did document for did:ion:1234abcd?

What is the value of signature?

I think we should not use DNS for this first interop project, but I'm excited to see the support for it exists.

[awoie]

@awoie Does uPort have an implementation/spec for this?

@christianlundkvist Yes, uPort is supporting the did:web method which is based on a .well-known URL hosting a DID Document. This establishes the linkage between a domain owner and a DID by leveraging existing Internet PKI, i.e., TLS certificates.

@OR13 see https://github.com/uport-project/specs/blob/develop/did-methods/https-did-method.md

But I believe the challenge here is to discover other DIDs than did:web.

[csuwildcat]

Yes, the more I have been thinking about it, using /.well-known/did is probably the most flexible, easiest to perform means of linking a DID to a domain. Here is one specific reason/issue it makes a lot easier:

When we start developing decentralized apps using DIDs/Identity Hubs, it would be best to leverage the existing Progressive Web App standards that browsers support today, and extend them with DID/decentralized app capabilities - we could call these 'DWAs'. Existing standard PWAs can be installed against a domain or subdomain - the last part being of particular interest. Many people write a PWA and host it on a place like GitHub or other site that provides a unique subdomain for each account. This allows users to have a really easy way to publish their PWAs, while the browser keeps each domain/subdomain separate, in terms of origin security scope.

If we went with /.well-known/did as our first, DIF-supported means of linking a DID to a domain/subdomain, it would we very easy for a developer to add a list of verifiable JWTs to a /.well-known/did JSON file, and work the same regardless of whether the dev was dealing with a base TLD or a subdomain.

Shall we flesh out a formal spec for /.well-known/did as a next step?

[OR13]

@awoie thanks! the uport did:web is awesome, however, it is prior work and creates a name conflict for the format of what we are wanting to do here, potentially....

@csuwildcat 's suggestions regarding the format of .well-known/did.json is different than how uport is using it.

I suggest we resolve this by not colliding the names.

UPort is defining a method for web based DIDs.

We are wanting to link one or more DIDs of varying methods to a website.

These are not the same, so they cannot rely on the same .well-known/did.

I think that what uport is doing with did:web is closer to what .well-known/did should be.

I think that what we are wanting to do with registering DIDs to a domain is more akin to something like:

.well-known/did-configuration, which should look similar to .well-known/openid-configuration

See here: https://auth0.com/docs/protocols/oidc/openid-connect-discovery

If we take this approach, we can describe one or more DIDs of varying methods, as well as meta data about their registration, or claims. The Service Endpoints for registered DIDs should include some back link to the configuration, but no bi-directional signature should be required. The root of trust for a domain should remain a person who can publish content on it (Let's Encrypt / DNS controller).

In order for a DID to be registered correctly in .well-known/did-configuration, there should be a signature that is verifiable from it, and the signature should be over a configuration property such that DIDs can be added over time without requiring updates from existing registered DIDs.

The configuration property should be something like:

{
domain: 'example.com',
// optional..
// admin: admin@example.com || did:example:123
}

A DID is a valid registered DID for a website IF and ONLY IF:

• the website serves a .well-known/did-configuration
• the did is present in the dids property of did-configuration
• there is a verifiable JWT from the did in the proofs property of did-configuration

Someone else should formalize all of this...

The main point being that a DID controller should be able to revoke a registration independent of a website update, by rotating the key used to issue the registration proof. This will work for any DID Method.

Example:

Request:

GET https://example.com/.well-known/did-configuration

Response;

{
  schema: "some json schema URL",
  claim: { domain: 'example.com' },
  dids: ["did:ethr:0123...", "did:btcr:567..."],
  proofs: ["JWT_1", "JWT_2"],
}

^ maybe there is a way to make this a verifiable presentation / get the VC WG to define this?

[csuwildcat]

Hey folks, I threw together a skeletal explainer doc for /.well-known/did-configuration: https://github.com/decentralized-identity/well-known/blob/master/did-configuration.md

@OR13 as you'll see, I am proposing a bit of a different format with some scoping mechanics that will enable things like PWAs across sites where subdomains are scoped to different users. Let me know what you think - hopefully we can use that repo to flesh out the explainer/spec itself.

[OR13]

@csuwildcat I have merged the PR for the demo based on the spec:

https://well-known.transmute-did.com/

(You may need to ignore SSL while cloudflare boots)

[OR13]

I'm going to consider this adopted.