diff --git a/spec/api.yaml b/spec/api.yaml index 003118b8..96cbb901 100644 --- a/spec/api.yaml +++ b/spec/api.yaml @@ -166,6 +166,24 @@ paths: application/json: schema: type: object + properties: + did: + type: object + description: "The DID Document." + pkarr: + type: string + description: "An unpadded base64URL-encoded representation of a full Pkarr payload, represented as 64 bytes sig, 8 bytes u64 big-endian seq, 0-1000 bytes of v concatenated; enabling independent verification." + types: + type: array + items: + type: integer + description: "The types associated with the DID." + sequence_numbers: + type: array + items: + type: integer + description: "The sequence numbers available for querying for this node." + required: [ did, pkarr ] "400": description: Invalid request. content: @@ -178,12 +196,6 @@ paths: application/json: schema: type: string - "501": - description: Historical resolution not supported by this gateway. - content: - application/json: - schema: - type: string /dids/types: get: tags: @@ -205,7 +217,7 @@ paths: description: type: string required: [ type, description ] - "501": + "404": description: Type indexing not supported by this gateway. content: application/json: @@ -243,24 +255,12 @@ paths: type: array items: type: string - "400": - description: Invalid request. - content: - application/json: - schema: - type: string "404": description: Type not found. content: application/json: schema: type: string - "501": - description: Type indexing not supported by this gateway. - content: - application/json: - schema: - type: string /difficulty: get: tags: @@ -280,7 +280,7 @@ paths: difficulty: type: integer required: [ hash, difficulty ] - "501": + "404": description: Retention proofs not supported by this gateway. content: application/json: diff --git a/spec/registry/spec.md b/spec/registry/spec.md index 3d92966d..bd728f5a 100644 --- a/spec/registry/spec.md +++ b/spec/registry/spec.md @@ -9,7 +9,7 @@ The DID DHT Method Specification Registry 1.0 **Draft Created:** November 20, 2023 -**Latest Update:** January 19, 2024 +**Latest Update:** January 26, 2024 **Editors:** ~ [Gabe Cohen](https://github.com/decentralgabe) @@ -40,7 +40,7 @@ Corresponds to the mapping, for a DID Document's DNS packet representation, of a | ----- | ------------------------------------------------------ | | 0 | [Ed25519](https://ed25519.cr.yp.to/) | | 1 | [secp256k1](https://datatracker.ietf.org/doc/html/rfc8812#section-3.1) | -| 2 | [secp256r1](https://neuromancer.sk/std/secg/secp256r1) | +| 2 | [secp256r1](https://neuromancer.sk/std/secg/secp256r1) / [P-256](https://neuromancer.sk/std/nist/P-256) | ::: note All keys are represented as JWKs [[spec:RFC7517]] in their **uncompressed** form. @@ -73,6 +73,24 @@ themselves discoverable via a [[ref:Gateway]]'s API. | Web App | https://schema.org/WebApplication | 6 | | Financial Institution | https://schema.org/FinancialService | 7 | +### Additional Properties + +DID Documents may contain [additional properties](https://www.w3.org/TR/did-core/#extensibility) not defined by the core data model. These +properties ****MAY**** be registered in the [[spec:DID-SPEC-REGISTRIES]], or in the following table. Independent of where +the property is registered, a mapping ****MUST**** be provided between the property and its DNS packet representation. + +To add additional properties and note their mappings, please [open a pull request](https://github.com/TBD54566975/did-dht-method/pulls). + +#### Service + +These properties are for use on a service object, in the value of [service](https://www.w3.org/TR/did-core/#services). + +| Property Name | Type | DNS Packet Representation | Example | +| ------------- | -------------------------- | ------------------------------------------------- | ------------------------------------------------------- | +| `sig` | String or array of strings | `enc=E` where `E` is a string or array of strings | id=s1;t=TestService;se=https://test-service.com/1;enc=1 | +| `enc` | String or array of strings | `sig=S` where `S` is a string or array of strings | id=s1;t=TestService;se=https://test-service.com/1;sig=2 | + + ### Interoperable DID Methods As an **OPTIONAL** extension, some existing DID methods can leverage `did:dht` to broaden their feature set. This registry serves diff --git a/spec/spec.md b/spec/spec.md index fd19d1bb..2056361d 100644 --- a/spec/spec.md +++ b/spec/spec.md @@ -9,7 +9,7 @@ The DID DHT Method Specification 1.0 **Draft Created:** October 20, 2023 -**Latest Update:** January 19, 2024 +**Latest Update:** January 26, 2024 **Editors:** ~ [Gabe Cohen](https://github.com/decentralgabe) @@ -203,6 +203,9 @@ values within each property are separated by a comma (`,`). - Across all properties, distinct elements are separated by semicolons (`;`) while array elements are separated by commas (`,`). +- Additional properties not defined by this specification ****MAY**** be represented in a [[ref:DID Document]] and +its corresponding DNS packet if the properties [are registered in the additional properties registry](registry/index.html#additional-properties). + An example of a _root record_ is as follows: | Name | Type | TTL | Rdata | @@ -465,7 +468,7 @@ DIDs can be indexed by type by adding a `_typ._did.` record to the DNS packet. A record. This record is a TXT record with the following format: - The record **name** is represented as a `_typ._did.` record. -- The record **data** is represented with the form `id=0,1,2` where the value is a comma-separated list of types from +- The record **data** is represented with the form `id=0,1,2` where the value is a comma-separated list of integer types from the [type index](#type-indexing). An example type record is as follows: @@ -477,8 +480,8 @@ An example type record is as follows: Types can be found and registered in the [DID DHT Registry](registry/index.html#indexed-types). ::: note -Identifying entities through type-based indexing is a preliminary and relatively unreliable method. It serves merely -as an initial phase in recognizing the identity linked to a [[ref:DID]]. To validate identity claims more robustly, +Identifying entities through type-based indexing is a preliminary and relatively unreliable practice. It serves +as an initial step in recognizing the identity linked to a [[ref:DID]]. To validate identity claims more robustly, it is essential to delve deeper, employing tools like verifiable credentials and examining related data. ::: @@ -575,8 +578,8 @@ Difficulty is exposed as an **OPTIONAL** endpoint based on support of [retention - **Path:** `/difficulty` - **Returns:** - `200` - Success. - - `hash` - **string** - The current hash. - - `difficulty` - **integer** - The current difficulty. + - `hash` - **string** - **REQUIRED** - The current hash. + - `difficulty` - **integer** - **REQUIRED** - The current difficulty. - `501` - Retention proofs not supported by this gateway. ```json @@ -623,10 +626,12 @@ DID by its type. - `id` - **string** - **REQUIRED** - ID of the DID to resolve. - **Returns:** - `200` - Success. - - `did` - **object** - A JSON object representing the DID Document. - - `types` - **array** - An array of [type strings](#type-indexing) for the DID. - - `sequence_numbers` - **array** - An sorted array of seen sequence numbers, used with [historical resolution](#historical-resolution). - - `400` - Invalid request. + - `did` - **object** - **REQUIRED** - A JSON object representing the DID Document. + - `pkarr` - **string** - **REQUIRED** - An unpadded base64URL-encoded representation of the full [[ref:Pkarr]] payload, represented as 64 bytes sig, + 8 bytes u64 big-endian seq, 0-1000 bytes of v concatenated; enabling independent verification. + - `types` - **array** - **OPTIONAL** - An array of [type integers](#type-indexing) for the DID. + - `sequence_numbers` - **array** - **OPTIONAL** - An sorted array of seen sequence numbers, used with [historical resolution](#historical-resolution). + - `400` - Invalid request. - `404` - DID not found. ```json @@ -654,20 +659,20 @@ DID by its type. "did:dht:i9xkp8ddcbcg8jwq54ox699wuzxyifsqx4jru45zodqu453ksz6y#0" ] }, + "pkarr": "", "types": [1, 4], "sequence_numbers": [1700356854, 1700461736] } ``` -Upon receiving a request to resolve a DID, the Gateway ****MUST**** query the DHT for the DID Document, and if found, -return the DID Document. If the records are not found in the DHT, the Gateway ****MAY**** fall back to its local storage. -If the DNS Packets contain a `_typ._did.` record, the Gateway ****MUST**** return the type index. +Upon receiving a request to resolve a DID, the [[ref:Gateway]] ****MUST**** query the DHT for the DID Document, and if found, +return the DID Document. If the records are not found in the DHT, the [[ref:Gateway]] ****MAY**** fall back to its local storage. +If the DNS Packets contain a `_typ._did.` record, the [[ref:Gateway]] ****MUST**** return the type index. -::: note -This API is not required to return the complete DNS packet but rather the DID Document and type index. If the full DNS -packet, with its signature data, is required it is ****RECOMMENDED**** to use the -[Relay API](https://github.com/Nuhvi/pkarr/blob/main/design/relays.md) directly. -::: +This API is returns a `pkarr` property which matches the payload of a [Pkarr Get Request](https://github.com/Nuhvi/pkarr/blob/main/design/relays.md#get), +when encoded as an unpadded base64URL string. Implementers are ****RECOMMENDED**** to verify the integrity of the response using +the `pkarr` data and reconstruct the DID Document themselves. The `did` property is provided as a utility which, without independent verification, +****SHOULD NOT**** be trusted. ##### Historical Resolution @@ -683,8 +688,10 @@ historical state for a given [[ref:DID]]. The following API can be used with spe - `seq` - **integer** - **OPTIONAL** - Sequence number of the DID to resolve - **Returns**: - `200` - Success. - - `did` - **object** - A JSON object representing the DID Document. - - `types` - **array** - An array of [type strings](#type-indexing) for the DID. + - `did` - **object** - **REQUIRED** - A JSON object representing the DID Document. + - `pkarr` - **string** - **REQUIRED** - An unpadded base64URL-encoded representation of the full [[ref:Pkarr]] payload, represented as 64 bytes sig, + 8 bytes u64 big-endian seq, 0-1000 bytes of v concatenated; enabling independent verification. + - `types` - **array** - **OPTIONAL** - An array of [type integers](#type-indexing) for the DID. - `400` - Invalid request. - `404` - DID not found for the given sequence number. - `501` - Historical resolution not supported by this gateway. @@ -706,7 +713,9 @@ stop republishing the DHT. If the DNS Packets contain a `_typ._did.` record, the - **Path:** `/did/types` - **Returns:** - `200` - Success. - - **array** - An array of objects describing the known types. + - **array** - An array of objects describing the known types of the following form: + - `type` - **integer** - **REQUIRED** - An integer representing the [type](#type-indexing). + - `description` - **string** - **REQUIRED** - A string describing the [type](#type-indexing). - `404` - Type indexing not supported. ```json @@ -731,7 +740,7 @@ stop republishing the DHT. If the DNS Packets contain a `_typ._did.` record, the - `limit` - **integer** - **OPTIONAL** - Specifies the maximum number of type records to retrieve (Default: `100`). - **Returns:** - `200` - Success. - - **array** - An array of DID Identifiers matching the associated type. + - **array** - **REQUIRED** - An array of DID Identifiers matching the associated type. - `400` - Invalid request. - `404` - Type not found. - `501` - Types not supported by this gateway.