Merge pull request #42 from swcurran/cleanup

Feedback cleanup and add links to implementations

spec/abstract.md

@@ -25,7 +25,7 @@ of `did:web`. It's features include the following.
   [[ref: Verifiable Credentials]] with the DID as the `credentialSubject`,
   signed by the DID.
 
-Combined, the additional feature enable greater trust and security without
+Combined, the additional features enable greater trust and security without
 compromising the simplicity of `did:web`. The incorporation of the DID Core
 compatible "/whois" path, drawing inspiration from the traditional WHOIS
 protocol [[spec:rfc3912]], offers an easy to use, decentralized, trust registry.

spec/definitions.md

@@ -114,7 +114,7 @@ associated DID document are created, resolved, updated, and deactivated. DID
 methods are defined using separate DID method specifications. This document is
 the DID Method Specification for `did:tdw`.
 
-[[def: verifiableConditions]]
+[[def: Verifiable Conditions, verifiableConditions]]
 
 ~ The (proposed) [verifiableConditions
 Specification](https://github.com/w3c-ccg/verifiable-conditions) defines a way

spec/implementors_guide.md

@@ -1,5 +1,16 @@
 ## Implementors Guide
 
+### Implementations
+
+Proof of concept implementations of `did:tdw` software for [[ref: DID Controllers]] and resolvers can be found here:
+
+- Typescript: [https://github.com/bcgov/trustdidweb-ts](https://github.com/bcgov/trustdidweb-ts)
+- Python: To be added
+
+Both currently (as of 2024.04.11) support all of the features of `did:tdw` except for [[ref:  Key Pre-Rotation]] and [[ref: Verifiable Conditions]].
+
+The Typescript implementation is currently less than 1000 lines of Typescript code.
+
 ### Using Pre-Rotation Keys
 
 Best practices are that the [[ref: DID Controller]] generates the active key for the DIDDoc where it can be used for "production" purposes, and generates the "next key" in an isolated location from production

spec/overview.md

@@ -91,6 +91,13 @@ The following is a `tl;dr` summary of how `did:tdw` works.
 An example of a `did:tdw` evolving through a series of versions can be seen in
 the [did:tdw Examples](#didtdw-example) of this specification.
 
+This draft specification was developed in parallel with the development of two proof
+of concept implementations. The specification/implementation interplay helped
+immensely in defining a practical, easy to use, easy to understand, DID method.
+The existing proof of concept implementations of the `did:tdw` DID Method are
+listed in the [Implementors Guide](#Implementations). The current Typescript
+implementation is less than 1000 lines of Typescript code.
+
 ### The `/whois` Use Case
 
 This DID Method introduces what we hope will be a widely embraced convention for
@@ -108,13 +115,14 @@ resolved (using a standard DID `service` that follows the [[ref: Linked-VP]]
 specification), a [[ref: Verifiable Presentation]] (VP) may be returned (if
 published by the DID Controller) containing [[ref: Verifiable Credentials]] with
 the DID as the `credentialSubject`, and the VP signed by the DID. Given a DID,
-one can find out who controls that DID by calling `<did>/whois` and processing
-the returned VP. That's powerful -- a decentralized trust registry. For
-`did:tdw`, the approach is very simple -- transform the DID to its HTTPS
-equivalent, and `GET <https>/whois`. Need to know who issued the VCs in the VP?
-Get the issuer DIDs from the VCs, and resolve `<issuer did>/whois`. This is
-comparable to walking a CA (Certificate Authority) hierarchy, but self-managed
-by the DID Controllers -- and the issuers that attest to them.
+one can gather verifiable data about the [[ref: DID Controller]] by resolving
+`<did>/whois` and processing the returned VP. That's powerful -- an efficient,
+highly decentralized, trust registry. For `did:tdw`, the approach is very simple
+-- transform the DID to its HTTPS equivalent, and execute a `GET <https>/whois`.
+Need to know who issued the VCs in the VP? Get the issuer DIDs from those VCs,
+and resolve `<issuer did>/whois` for each. This is comparable to walking a CA
+(Certificate Authority) hierarchy, but self-managed by the DID Controllers --
+and the issuers that attest to them.
 
 The following is a use case for the `/whois` capability. Consider an example of
 the `did:tdw` controller being a mining company that has exported a shipment and

spec/specification.md

@@ -306,7 +306,7 @@ DID](#publishing-a-parallel-didweb-did) section of this specification.
 To deactivate the DID, the [[ref: DID Controller]] **SHOULD** add to the [[ref:
 DID log entry]] [[ref: parameters]] the item `"deactivated": true`. A [[ref: DID
 Controller]] **MAY** update the DIDDoc further to indicate the deactivation of
-the DID, such as removing the `authorization` key type entries, preventing
+the DID, such as removing the `authentication` key type entries, preventing
 further updates to the DID/DIDDoc.
 
 A resolver encountering in the [[ref: DID log entry]] [[ref: parameters]] the
@@ -356,10 +356,10 @@ items are defined below.
   - By default, the value is initialized to `sha256`.
   - Acceptable values:
     - `sha256`: Use the `SHA-256` algorithm from [[spec:rfc4634]].
-- `cryptosuite`: The Data Integrity cryptosuite to use when generating and verifying the authorization proofs on the [[ref: DID log entries]].
+- `cryptosuite`: The Data Integrity cryptosuite to use when generating and verifying the authentication proofs on the [[ref: DID log entries]].
   - By default, the value is initialized to `eddsa-2022`
   - Acceptable values:
-    - `eddsa-2022`: Use the [EDDSA 2022](https://github.com/digitalbazaar/eddsa-2022-cryptosuite) cryptosuite.
+    - `eddsa-jcs-2022`: Use the [eddsa-jcs-2022](https://www.w3.org/TR/vc-di-eddsa/#eddsa-jcs-2022) cryptosuite.
 - `prerotation`: A boolean value indicating that subsequent authentication keys
   added to the DIDDoc (after this version) **MUST** have their hash included in
   a `nextKeys` parameter item.
@@ -393,7 +393,7 @@ items are defined below.
     repeated calls to get all of the previous versions of the DIDDoc. By caching
     the DIDDoc state, the resolver would not have to retrieve and process the
     [[ref: DID Log]] on every call.
-  - A Web Server handling one or more `did.jsonl` file **MAY** be configured to
+  - A Web Server handling one or more `did.jsonl` files **MAY** be configured to
    use a comparable HTTP TTL per [[spec-inform:rfc9111]].
 
 #### SCID Generation and Validation