§ Decentralized Web Node

Specification Status: Draft

Latest Draft: identity.foundation/decentralized-web-node/spec

Previous Draft: 0.0.1-predraft

Companion Guide v0.0.1

Chairs

Andor Kesselman

Liran Cohen

Editors:

Daniel Buchner (Block)

Tobias Looker (Mattr)

Contributors:

Henry Tsai (Microsoft)

XinAn Xu (Microsoft)

Moe Jangda (Block)

Participate:

GitHub repo

File a bug

Commit history

§ Abstract

Most digital activities between people, organizations, devices, and other entities require the exchange of messages and data. For entities to exchange messages and data for credential, app, or service flows, they need an interface through which to store, discover, and fetch data related to the flows and experiences they are participating in. A Decentralized Web Node (DWN) is a data storage and message relay mechanism entities can use to locate public or private permissioned data related to a given Decentralized Identifier (DID). Decentralized Web Nodes are a mesh-like datastore construction that enable an entity to operate multiple nodes that sync to the same state across one another, enabling the owning entity to secure, manage, and transact their data with others without reliance on location or provider-specific infrastructure, interfaces, or routing mechanisms.

§ Status of This Document

Decentralized Web Node is a DRAFT specification under development within the Decentralized Identity Foundation (DIF). It is an active work item of the Secure Data Storage Working Group at DIF. It incorporates requirements and learnings from related work of many active industry players into a shared specification that meets the collective needs of the community.

The specification will be updated to incorporate feedback, from DIF members and the wider community, with a reference implementation being developed within DIF that exercises the features and requirements defined here. We encourage reviewers to submit GitHub Issues as the means by which to communicate feedback and contributions.

§ Terminology

Decentralized Web Node

A decentralized personal and application data storage and message relay node, as defined in the DIF Decentralized Web Node specification. Users may have multiple Nodes that replicate their data between them.

Decentralized Identifiers

Unique ID URI string and PKI metadata document format for describing the cryptographic keys and other fundamental PKI values linked to a unique, user-controlled, self-sovereign identifier in a target system (e.g., blockchain, distributed ledger).

§ Topology

§ Technical Stack

Decentralized Web Nodes are comprised of the following component layers, each of which is defined in this specification to ensure multiple Decentralized Web Node implementations can be used together and operate as a single logical unit for users.

§ Protocols

Protocols are used to describe common rules that DWNs will follow when dealing with specific types and structures of data. Through Protocol Definitions a DWN Owner can define how a protocol should behave.

The definition defines types, as well as their structure allowing for hierarchial relationships for data types, as well as roles, object capabilities, and enforced limitations such as data payload size.

This will promote interoperability between users and apps, avoiding bespoke implementation details and interactivity often needed within traditional application development.

{
  "protocol": "https://example.com/protocol/image-storage",
  "types": {
    "image": {
      "schema": "https://example.com/schemas/image",
      "dataFormats": [
        "image/png",
        "image/jpeg",
        "image/gif"
      ]
    },
    "metadata": {
      "schema": "https://example.com/schemas/metadata",
      "dataFormats": [
        "application/json"
      ]
    }
  },
  "structure": {
    "image": {
      "$size": {
        "max": 500000000
      },
      "metadata": {
        "$size": {
          "max": 100000
        }
      }
    }
  }
}

{
  "protocol": "https://example.com/protocol/image-sharing",
  "types": {
    "image": {
      "schema": "https://example.com/schemas/image",
      "dataFormats": [
        "image/png",
        "image/jpeg",
        "image/gif"
      ]
    },
    "metadata": {
      "schema": "https://example.com/schemas/metadata",
      "dataFormats": [
        "application/json"
      ]
    },
    "viewer": {
      "schema": "https://example.com/schemas/viewer",
      "dataFormats": [
        "application/json"
      ]
    },
    "writer": {
      "schema": "https://example.com/schemas/writer",
      "dataFormats": [
        "application/json"
      ]
    }
  },
  "structure": {
    "viewer": {
      "$role": true
    },
    "writer": {
      "$role": true
    },
    "image": {
      "$size": {
        "max": 500000000
      },
      "$actions": [
        {
          "role": "viewer",
          "can": [
            "read",
            "query"
          ]
        },
        {
          "role": "writer",
          "can": [
            "create",
            "update",
            "delete"
          ]
        }
      ],
      "metadata": {
        "$size": {
          "max": 100000
        },
        "$actions": [
          {
            "role": "viewer",
            "can": [
              "read",
              "query"
            ]
          },
          {
            "who": "author",
            "of": "image",
            "can": [
              "create",
              "update",
              "delete"
            ]
          }
        ]
      }
    }
  }
}

§ Service Endpoints

The following DID Document Service Endpoint entries MUST be present in the DID Document of a target DID for resolution to properly locate the URI for addressing a DID owner’s Decentralized Web Nodes:

{
  "id": "did:example:alice",
  "service": [{
    "id": "#dwn",
    "type": "DecentralizedWebNode",
    "enc": [
      "#dwn-enc"
    ],
    "sig": [
      "#dwn-sig"
    ],
    "serviceEndpoint": [
      "did:example:host",
      "https://dwn.example.com"
    ]
  }]
}

• Service Endpoints MUST contain an id property and it MUST be set to #dwn.
• Service Endpoints MUST contain a type property and it MUST be set to DecentralizedWebNode.
• Service Endpoints MUST contain a serviceEndpoint property and it MUST be set to one of the following:
  • a string value which represents the URL associated with the DWN
  • an array of string values, each of which represents the URL associated with a DWN
• If a Service Endpoint URL is a DID, it MUST NOT not be followed more than 1 level deep when resolving.
• Service Endpoints MUST contain an enc property which MUST be a string value or an array of string values, each of which represents a keyId associated with encrypting data.
• Service Endpoints MUST contain a sig property which MUST be a string value or an array of string values, each of which represents a keyId associated with signing data.

§ Messages