Using an "action" state, the registrar can ask a client to perform some action (e.g. sign a payload, send coins, agree to a legal text, etc.). Should this state contain an expiration time after which it is not valid anymore? This could be part of didRegistrationMetadata.

Example:

{
    "jobId": "1234",
    "didState": {
      "state": "action",
      "action": "signPayload",
      "signingRequest": {
        "signingRequest1": {
          ...
        }
      }
    },
    "didRegistrationMetadata": {
        "stateExpires": "1541499210"
    },
    "didDocumentMetadata": { }
}

In certain cases, the DID Registrar returns private keys and other secrets to a client (see didState.secret).

Should we support that in an encrypted form?

See #6 (review)

In cases when a DID Registrar returns generated secrets (such as private DID controller keys) to a client, we should specify the format of those secrets (probably re-using JWK and other standards).

Depending on the DID method, not all returned secrets may be private keys, they could also be seeds or other things.

See https://identity.foundation/did-registration/#didstatesecret.

In cases where a DID Registrar interacts with an external wallet (see External Secret Mode) or a client-managed wallet (see Client-Managed Secret Mode), we should specify those interfaces.

Existing work that is related to this:

• Traditional Certificate Signing Requests (CSRs) as used by Let's Encrypt etc.
• Universal Wallet in CCG
• WebKMS in CCG

If a DID Registrar exposes an HTTPS interface, how exactly are the operations, inputs, and outputs transmitted over HTTPS?

It seems the straightforward approach is to have one HTTPS endpoint for each one of the create(), update(), and deactivate() operations, using POST calls.

How would we use HTTP headers and status codes?

See this OpenAPI definition for an initial design.

In the experimental client-managed secret flow with did:sov, the client can include a public key in the initial request for DID creation:

{
  "options": {
    "network": "danube",
    "clientSecretMode": true,
    "publicKey": "DHu3PwQNjEGv2qNanA7vxytLr83CLutKhqeKZwjRi2Yd"
  },
  "secret": { },
  "didDocument": { }
}

Maybe the public key should be represented as JWK, and maybe it should be possible to include multiple (named?) public keys. Their meaning and use may depend on the DID method. Also, we should explain when public keys using for creating DIDs will also show up as verificationMethods in the DID document, and when not. (I.e. sometimes the keys that control a DID are not the same as the keys that are listed in the DID document).

Example:

{
    "options": {
        "network": "danube",
        "clientSecretMode": true,
        "publicKey": {
            "mymaincontrolkey": {
                "kid": "...",
                "kty": "EC",
                "crv": "secp256k1",
                "x": "DHu3PwQNjEGv2qNanA7vxytLr83CLutKhqeKZwjRi2Yd"
            },
            "myotherkey": {
                ...
            }
        }
    },
    "secret": { },
    "didDocument": {
        "@context": ...,
        "id": ...,
        "verificationMethod": [ {
            "id": "...",
            "type": "EcdsaSecp256k1VerificationKey2019",
            "publicKeyBase58": "DHu3PwQNjEGv2qNanA7vxytLr83CLutKhqeKZwjRi2Yd"
        } ]
    }
}

Thinking about where I see this going, I think one of the clear places I could see this getting implemented would be as a Browser API since DIDs have been standardized at W3C. However, one thing that's certain is that browser vendors won't want to support every did method under the sun so I'm thinking it would be useful for us to define a method to polyfill a method into the browser so that the standard interface APIs could be used by them. Then browser vendors would only need to implement 1 or 2 did methods by default with the additional option that a new method can be added into the browser very easily while also converging their usage in a meaninful way like this spec does.

What's your thoughts on adding a addMethodDriver operation in a way that would allow for the create API to call those methods using the polyfill?

In the HTTP(S) binding, we currently use a few HTTP status codes such as 200, 201, 400, 500.

Suggested by @cihanss, it would probably be useful to make use of additional HTTP status codes in certain cases, e.g.:

• 401 or 402 if didState.action="getVerificationMethod"
• 402 if payment is required for DID methods such as did:btcr
• 303 if didState.action="redirect"
• etc.

Objective:

• Most DID registries require users to onboard to get write access
• Process may be both DID-method and DID-method instance/implementation-specific

Can we define a generic flow (or flows) that cover most cases, are light for wallet providers and don't or minimally disrupt the current processes?

Proposal:

• Present two flows that would cover most of the cases
  • user is redirected to the onboarding page and all the onboarding-related operations are performed there
  • onboarding via API (example: btcr)
• The document would allow for other processes that cannot be covered in the 2 cases above

https://identity.foundation/did-registration/#didstatestate