did:webvh DID Method

https://identity.foundation/didwebvh
Admin
The did:webvh DID Method enhances the did:web DID method by providing complementary features that...
Tokens:19,105
Snippets:276
Trust Score:9.4
Update:4 months ago
Show doc for...
Tokens:
Raw
### DID WebVH Parameters Example

Source: https://identity.foundation/didwebvh

An example of the 'parameters' property in the first DID Log entry for did:webvh. This demonstrates the structure and common parameters used.

```json
{
  "portable": true,
  "updateKeys": [
    "z82LkqR25TU88tztBEiFydNf4fUPn8oWBANckcmuqgonz9TAbK9a7WGQ5dm7jyqyRMpaRAe"
  ],
  "nextKeyHashes": [
    "enkkrohe5ccxyc7zghic6qux5inyzthg2tqka4b57kvtorysc3aa"
  ],
  "method": "did:webvh:1.0",
  "scid": "{SCID}"
}
```

--------------------------------

### DID Document Metadata Example

Source: https://identity.foundation/didwebvh

This JSON object represents the DID Document Metadata returned when resolving a did:webvh DID. It includes details about the DID's version, timestamps, and status.

```json
{
  "versionId": "1-QmRRaLXwc6BjBuBPosSupJwEQ8w9f3znP7yfbpGfwcnLr6",
  "versionTime": "2025-01-23T04:12:36Z",
  "created": "2025-01-23T04:12:36Z",
  "updated": "2025-01-23T04:12:36Z",
  "scid": "QmPEQVM1JPTyrvEgBcDXwjK4TeyLGSX1PxjgyeAisdWM1p",
  "portable": false,
  "deactivated": false,
  "ttl": "3600",
  "witness": { ...
  },
  "watchers: [ ...
  ]
}
```

--------------------------------

### Example Preliminary Log Entry for Entry Hash Generation

Source: https://identity.foundation/didwebvh

This is a preliminary log entry used as input for generating an entry hash. For the first log entry, the input versionId is the SCID of the DID.

```json
{"versionId": "QmdmPkUdYzbr9txmx8gM2rsHPgr5L6m3gHjJGAf4vUFoGE", "versionTime": "2025-04-01T17:39:50Z", "parameters": {"witness": {"threshold": 2, "witnesses": [{"id": "did:key:z6Mkkc51mg2vpQzKWAbWQZupeGYhowaBjYkmvcKMTqteqHB4", "weight": 1}, {"id": "did:key:z6MkuDdJdKLCgwZuQuEi9xG6LVgJJ9Tebr74CXPYPSumqgJs", "weight": 1}, {"id": "did:key:z6MkoSWmQyp4fTk4ZQy4KUsss9dFX51XfEUzKKKj1J1JUsrF", "weight": 1}]}, "updateKeys": ["z6MkgzBDcBFV3sk4ypPE5YXMZHmS213A3HpYY2LmcVKV15jr"], "nextKeyHashes": ["QmZreDcjvWEpyRFznQeExWNCsvMLk5i59AcRJJuQC8UodJ"], "method": "did:webvh:0.5", "scid": "QmdmPkUdYzbr9txmx8gM2rsHPgr5L6m3gHjJGAf4vUFoGE"}, "state": {"@context": ["https://www.w3.org/ns/did/v1"], "id": "did:webvh:QmdmPkUdYzbr9txmx8gM2rsHPgr5L6m3gHjJGAf4vUFoGE:domain.example"}}
```

--------------------------------

### GET Watcher Witness

Source: https://identity.foundation/didwebvh

Returns the latest witness.json file for the given SCID.

```APIDOC
## GET /witness?scid=<SCID>

### Description
Retrieves the most recent `witness.json` file associated with a specific SCID.

### Method
GET

### Endpoint
`/witness?scid=<SCID>`

### Parameters
#### Query Parameters
- **scid** (string) - Required - The Service Context ID (SCID) for which to retrieve the witness file.
```

--------------------------------

### GET Watcher Resource

Source: https://identity.foundation/didwebvh

Retrieves the requested resource for a given SCID and resource path.

```APIDOC
## GET /resource?scid=<SCID>&path=<resourcePath>

### Description
Retrieves a specific resource identified by its path, associated with a given SCID.

### Method
GET

### Endpoint
`/resource?scid=<SCID>&path=<resourcePath>`

### Parameters
#### Query Parameters
- **scid** (string) - Required - The Service Context ID (SCID) of the resource.
- **path** (string) - Required - The path to the requested resource.
```

--------------------------------

### GET Watcher Log

Source: https://identity.foundation/didwebvh

Returns the latest DID Log for a given SCID.

```APIDOC
## GET /log?scid=<SCID>

### Description
Retrieves the most recent DID Log associated with a specific SCID.

### Method
GET

### Endpoint
`/log?scid=<SCID>`

### Parameters
#### Query Parameters
- **scid** (string) - Required - The Service Context ID (SCID) to retrieve the log for.
```

--------------------------------

### DID Resolution Error Metadata Example

Source: https://identity.foundation/didwebvh

This JSON structure shows the `didResolutionMetadata` returned when a DID resolution error occurs. It includes a general error code and supplemental Problem Details conforming to RFC9457.

```json
"didResolutionMetadata": {
  "error": "invalidDid",
  "problemDetails": {
    "type": "https://w3id.org/security#INVALID_CONTROLLED_IDENTIFIER_DOCUMENT_ID",
    "title": "The resolved DID is invalid.",
    "detail": "Parse error of the resolved DID at character 3, expected ':'"
  }
}
```

--------------------------------

### DID Witness Proofs File Data Model

Source: https://identity.foundation/didwebvh

This JSON structure represents the data model for the did-witness.json file, which contains proofs from witnesses for specific DID log versions. Each entry includes a versionId and an array of Data Integrity proofs.

```json
[
  {
    "versionId": "1-Qmba111111...",
    "proof": [{ ... }, { ... }]
  },
  {
    "versionId": "2-Qzmb222222...",
    "proof": [{ ... }, { ... }]
  }
]

```

--------------------------------

### DID Webvh ABNF Syntax

Source: https://identity.foundation/didwebvh

This Augmented Backus-Naur Form (ABNF) defines the formal syntax for a DID using the 'webvh' method. It specifies the required components, including the SCID and domain name structure.

```abnf
webvh-did = "did:webvh:" scid ":" domain-segment 1+( "." domain-segment ) [ percent-encoded-port ] *( ":" path-segment )
scid = 46(base58-alphabet) ; The characters in the base58-btc-alphabet are as defined in the referenced W3C "Controller Documents" specification 
domain-segment = ; A part of a domain name as defined in RFC3986, such as "example" and "com" in "example.com"
percent-encoded-port = "%3A" ( "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ) 1*4( DIGIT )
path-segment= ; A part of a URL path as defined in RFC3986, such as "path", "to", "folder" in "path/to/folder"
```

--------------------------------

### DID Witness Parameter Structure

Source: https://identity.foundation/didwebvh

Defines the JSON structure for the 'witness' parameter in a DID Log entry. This includes the required 'threshold' and an array of 'witnesses', each with a unique 'id'.

```json
"witness" : {
  "threshold": n,
  "witnesses" : [
      {
         "id": "<did:key DID of witness>"
      }
   ]
}
```

--------------------------------

### POST Watcher Log Update

Source: https://identity.foundation/didwebvh

Notifies the watcher of a log update, prompting retrieval of the latest DID Log and witness file.

```APIDOC
## POST /log?did=<DID>

### Description
Notifies the watcher about a log update for a given DID. This triggers the watcher to retrieve the latest DID Log and witness file. The DID is used as a query parameter to handle cases where the DID might have moved to a new web location, while the watcher continues indexing using its SCID.

### Method
POST

### Endpoint
`/log?did=<DID>`

### Parameters
#### Query Parameters
- **did** (string) - Required - The Decentralized Identifier (DID) to notify the watcher about.
```

--------------------------------

### DID:webvh Oblivious HTTP Flow

Source: https://identity.foundation/didwebvh

Illustrates the sequence of interactions when using Oblivious HTTP with a did:webvh server or watcher. This flow helps understand how privacy is maintained by encrypting requests and responses between different participants.

```sequenceDiagram
sequenceDiagram
    participant Client as Client (Wallet / Resolver / Verifier)
    participant Relay as OHTTP Relay (e.g., Fastly)
    participant Gateway as OHTTP Gateway (Ecosystem-Operated)
    participant Server as did:webvh Server / Watcher

    Client->>Relay: Encapsulated OHTTP Request<br/>(encrypted with Gateway’s key)
    Relay->>Gateway: Forward opaque blob
    Gateway->>Server: Decapsulated HTTP Request<br/>(to did:webvh server or watcher)
    Server-->>Gateway: HTTP Response
    Gateway-->>Relay: Encapsulated OHTTP Response
    Relay-->>Client: Forward opaque blob (encrypted response)

    note over Relay,Gateway: Relay sees client IP but not content.<br/>Gateway sees content but not client IP.
```

--------------------------------

### POST Watcher Resource Update

Source: https://identity.foundation/didwebvh

Notifies the watcher of a new or updated resource.

```APIDOC
## POST /resource?scid=<SCID>&path=<resourcePath>

### Description
Notifies the watcher about a new or updated resource. This ensures the watcher's cache is up-to-date with the latest resource information.

### Method
POST

### Endpoint
`/resource?scid=<SCID>&path=<resourcePath>`

### Parameters
#### Query Parameters
- **scid** (string) - Required - The Service Context ID (SCID) associated with the resource.
- **path** (string) - Required - The path of the new or updated resource.
```

--------------------------------

### Implicit #whois Service Definition

Source: https://identity.foundation/didwebvh

This JSON object represents the default structure for the #whois service endpoint in a did:webvh DID. It uses the LinkedVerifiablePresentation type and specifies the service endpoint based on a standard DID-to-HTTPS translation.

```json
{
  "@context": "https://identity.foundation/linked-vp/contexts/v1",
  "id": "#whois",
  "type": "LinkedVerifiablePresentation",
  "serviceEndpoint": "<did-to-https-translation>/whois.vp"
}
```

--------------------------------

### Implicit relativeRef Service Definition for did:webvh

Source: https://identity.foundation/didwebvh

This JSON object represents the implicit service definition for the 'relativeRef' type used in did:webvh DID URL path resolution. It is automatically used when no explicit 'files' service is defined in the DID Document.

```json
{
  "id": "#files",
  "type": "relativeRef",
  "serviceEndpoint": "https://example.com/"
}
```
Tokens:
Raw