Add extension mechanism; update language around types being integers (#…

…110) * update language around types being integers * add extension ability * add text around pkarr response; update API * Apply suggestions from code review Co-authored-by: Frank Hinek <[email protected]> --------- Co-authored-by: Frank Hinek <[email protected]>
decentralized-identity · Feb 1, 2024 · fca6f68 · fca6f68
1 parent 8f24836
commit fca6f68
Show file tree

Hide file tree

Showing 3 changed files with 71 additions and 44 deletions.
diff --git 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
@@ -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
@@ -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": "<unpadded-base64URL-encoded pkarr payload as [sig][seq][v]>",
   "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.