Merge pull request #146 from swcurran/didwebvh

Update the next version of the spec to be did:webvh

README.md

@@ -1,6 +1,7 @@
-# Trust DID Web - A DID Method
+# The `did:webvh` DID Method -- `did:web` + Verifiable History
 
-The spec repository for did:tdw -- Trust DID Web DID method.
+The spec repository for the `did:webvh` DID Method. `did:webvh` is `did:web`
+extended to include the Verifiable History of the DID.
 
 Read the spec: [https://identity.foundation/trustdidweb](https://identity.foundation/trustdidweb)
 
@@ -10,23 +11,19 @@ Proof of concept implementations available:
 - Python: [https://github.com/bcgov/trustdidweb-py](https://github.com/bcgov/trustdidweb-py)
 - Go: [https://github.com/nuts-foundation/trustdidweb-go](https://github.com/nuts-foundation/trustdidweb-go)
 
-## Current Status of the Specification -- updated: 2024-11-29
+## Current Status of the Specification
 
-The current stable version of the specification is **v0.4**. It is the landing page
-of the [rendered specification](https://identity.foundation/trustdidweb/) and
-has been snapshotted into the `spec-v0.4` folder in this repo. Active work is happening (in
-the `spec`) folder on the next version of the specification ([rendered
-here](https://identity.foundation/trustdidweb/next)). The editors will announce
-when that new version is stable, assigned a version number, and becomes the next
-current version of the specification. Updates in that version will included at
-least changes in the pre-rotation handling, witnesses, and will include a name
-change to the DID Method.
+The current stable version of the specification can be found at
+[https://identity.foundation/trustdidweb](https://identity.foundation/trustdidweb).
+See any guidance there about the status of the specification -- past versions,
+upcoming changes, etc.
 
 ## Abstract
 
-The `did:tdw` (Trust DID Web) method is an enhancement to the
-`did:web` protocol, providing a complementary web-based DID method that addresses limitations
-of `did:web`. It's features include the following.
+The `did:webvh` DID Method is an enhancement to the well-known `did:web` DID
+method, providing a complementary web-based DID method that addresses
+limitations of `did:web`, most notability, the verifiable history for which it
+is name. `did:webvh` features include the following.
 
 - Ongoing publishing of all DID Document (DIDDoc) versions for a DID instead of,
   or alongside a `did:web` DID/DIDDoc.
@@ -51,13 +48,13 @@ of `did:web`. It's features include the following.
   Verifiable Credentials with the DID as the `credentialSubject`,
   signed by the DID.
 
-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, offers an easy to use, decentralized, trust registry.
-This `did:tdw` aims to establish a more trusted and secure web environment by
-providing robust verification processes and enabling transparency and
-authenticity in the management of decentralized digital identities.
+Combined, the additional features enable greater trust, security and
+verifiability without compromising the simplicity of `did:web`. The incorporation
+of the DID Core compatible "/whois" path, drawing inspiration from the
+traditional WHOIS protocol, offers an easy to use, decentralized, trust
+registry. `did:webvh` aims to establish a more trusted and secure web
+environment by providing robust verification processes and enabling transparency
+and authenticity in the management of decentralized digital identities.
 
 ## Contributing to the Specification
 
@@ -87,7 +84,7 @@ The specification is currently in [Spec-Up] format. See the
 ## Publishing Previous Spec Versions
 
 [Spec-Up] allows for multiple versions of the spec to be rendered and accessed
-on the same site. We use that feature for the `did:tdw` spec to snapshot
+on the same site. We use that feature for the `did:webvh` DID Method spec to snapshot
 previous versions of the spec for reference.
 
 To create a snapshot of a version:
@@ -116,27 +113,27 @@ To create a snapshot of a version:
 
 ## Handling Version Transitions
 
-In the lifecycle of the specification, there will be times when the version is
-stable, but clarifications may be added, and when new versions are being defined
-with breaking changes.  We use the Spec-Up feature to have multiple versions
-(described above) to enable that, but it gets a little tricky. Notably, we want
+In the lifecycle of the specification, there will be times when the latest version is
+stable, with clarifications being added, and other times when new versions are being defined
+with breaking changes.  We use the Spec-Up multiple versions feature
+(as described above) to support that, but it can get a little tricky. Notably, we want
 the landing page for the specification to **always** be the current version of
 the specification, **and** we want all "in progress" work to be to made to the
-single, primary specification (the files in the `spec` folder), so that GitHub
-holds the full evolution of the specification.  To enable that, we adjust as
+single, primary specification -- the files in the `spec` folder -- so that GitHub
+holds the full history of the specification.  To enable that, we adjust as
 needed the `"output_path"` in the `specs.json` file to define what version of
 the spec is on the specification landing page -- the spec version whose
 `"output_path"` is set to `"./"`).
 
-Here's how we do that:
+Here's how we do that in different situations:
 
 - When the specification is stable, the `spec` folder is the landing page, and
-  past versions are linked in the `header.md` file as "past versions".
+  past versions are linked in that folder's `header.md` file as "past versions".
 - When a new version of the specification with breaking changes is ready to be worked on:
   - Snapshot the stable specification version by creating a new directory (e.g.,
     `spec-v0.4`) and copying the files from the `spec` folder into the new
-    folder
-  - Create a new entry in the `specs.json` file for the version.
+    folder.
+  - Create a new entry in the `specs.json` file for that new snapshot version.
   - Set the `output_path` of the new version (e.g., `spec-v0.4`) to be `"./"`,
     so that it becomes the landing page.
   - Change the `output_path` of the primary `spec` folder entry to `"./next"`.

spec/abstract.md

@@ -1,14 +1,14 @@
 ## Abstract
 
-Trust DID Web (`did:tdw`) is an enhancement to the `did:web` DID method,
+DID Web + Verifiable History (`did:webvh`) is an enhancement to the `did:web` DID method,
 providing complementary features that address `did:web`'s
-limitations. `did:tdw` features include:
+limitations as a long-lasting DID. `did:webvh` features include:
 
-- Ongoing publishing of all DID Document ([[ref: DIDDoc]]) versions for a DID instead of,
-  or alongside a current `did:web` DID/DIDDoc.
 - The same DID-to-HTTPS transformation as `did:web`.
-- Supports the same [High Assurance DIDs with DNS] mechanism.
-- The ability to resolve the full history of the DID using a verifiable chain of
+- Ongoing publishing of the full history of the DID, including all of the DID
+  Document ([[ref: DIDDoc]]) versions instead of, or alongside an existing
+  `did:web` DIDDoc.
+- The ability to resolve the full history of the DID using a verifiable chain of]
   updates to the [[ref: DIDDoc]] from genesis to deactivation.
 - A [[ref: self-certifying identifier]] (SCID) for the DID. The [[ref: SCID]], globally unique and
   embedded in the DID, is derived from the initial [[ref: DID log entry]]. It ensures the integrity
@@ -23,6 +23,7 @@ limitations. `did:tdw` features include:
   control of a DID in cases where an active private key is compromised.
 - An optional mechanism for having collaborating [[ref: witnesses]]
   that approve of updates to the DID by a [[ref: DID Controller]] before publication.
+- Supports the same [High Assurance DIDs with DNS] mechanism.
 - DID URL path handling that defaults (but can be overridden) to automatically
   resolving `<did>/path/to/file` by using a comparable DID-to-HTTPS translation
   as for the [[ref: DIDDoc]].
@@ -35,9 +36,9 @@ limitations. `did:tdw` features include:
 
 [High Assurance DIDs with DNS]: https://datatracker.ietf.org/doc/draft-carter-high-assurance-dids-with-dns/
 
-Combined, the additional features enable greater trust and security without
+Combined, the additional features enable greater trust, security and verifiability without
 compromising the simplicity of `did:web`.
 
-For more information about the Trust DID Web (`did:tdw`) DID method and how (and
+For information beyond this specification about the (`did:webvh`) DID method and how (and
 where) it is used in practice, please visit
-[https://didtdw.org/](https://didtdw.org/)
+[https://didwebvh.info/](https://didwebvh.info/)

spec/definitions.md

@@ -3,7 +3,7 @@
 [[def: base58btc]]
 
 ~ Applies [[spec:draft-msporny-base58-03]] to convert
-data to a `base58` encoding. Used in `did:tdw` for encoding hashes for [[ref: SCIDs]] and [[ref: entry hashes]].
+data to a `base58` encoding. Used in `did:webvh` for encoding hashes for [[ref: SCIDs]] and [[ref: entry hashes]].
 
 [[def: Data Integrity]]
 
@@ -50,11 +50,11 @@ in the [[ref: DID Log]].
 ~ DID methods are the mechanism by which a particular type of DID and its
 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`.
+the DID Method Specification for `did:webvh`.
 
-[[def: DID Portability, DID:tdw portability, `DID:tdw` portability, portability]]
+[[def: DID Portability, did:webvh portability, `did:webvh` portability, portability]]
 
-~ `did:tdw` portability is the capability to change the DID string for the
+~ `did:webvh` portability is the capability to change the DID string for the
 DID while retaining the [[ref: SCID]] and the history of the DID. This is useful
 when forced to change (such as when an organization is acquired by another,
 resulting in a change of domain names) and when changing DID hosting service
@@ -66,8 +66,8 @@ providers.
 is a DID method that leverages the Domain Name System (DNS) to perform the DID operations.
 It is valued for its simplicity and ease of deployment compared to [[ref: DID methods]] that are
 based on distributed ledgers or blockchain technology, but also comes with increased
-challenges related to trust and security. `did:web` provides a starting point for `did:tdw`,
-which complements `did:web` with specific features to address the challenges
+challenges related to trust, security and verifiability. `did:web` provides a starting point for `did:webvh`,
+which complements `did:web` with specific features to address its challenges
 while still providing ease of deployment.
 
 [[def: eddsa-jcs-2022]]
@@ -80,7 +80,7 @@ the cryptosuite can be found in the specification, here:
 
 [[def: Entry Hash, entryHash, entry hashes]]
 
-~ A `DID:tdw` entry hash is a hash generated using a formally defined process
+~ A `did:webvh` entry hash is a hash generated using a formally defined process
 over the input data to a [[ref: log entry]], excluding the [[ref: Data Integrity]]
 proof. The input data includes content from the predecessor to the
 version of the DID, ensuring that all the versions are "chained" together in a
@@ -139,16 +139,16 @@ multi-signature is considered valid.
 
 [[def: parameters, parameter]]
 
-~ `did:tdw` parameters are a defined set of configurations that control how the
+~ `did:webvh` parameters are a defined set of configurations that control how the
 issuer has generated the DID, and how the resolver must process the DID [[ref:
 Log entries]]. The use of parameters allows for the controlled evolution of
-`did:tdw` log handling, such as evolving the set of permitted hash algorithms or
+`did:webvh` log handling, such as evolving the set of permitted hash algorithms or
 cryptosuites. This enables support for very long lasting identifiers -- decades.
 
 [[def: self-certifying identifier, self-certifying identifiers, SCID, SCIDs]]
 
 ~ An object identifier derived from initial data such that an attacker could not
-create a new object with the same identifier. The input for a `DID:tdw` SCID is
+create a new object with the same identifier. The input for a `did:webvh` SCID is
 the initial [[ref: DIDDoc]] with the placeholder `{SCID}` wherever the SCID is to be
 placed.
 
@@ -168,7 +168,7 @@ signs the [[ref: verifiable presentation]].
 [[def: witness, witnesses]]
 
 ~ Witnesses are participants in the process of creating and verifying a version
-of a `DID:tdw` [[ref: DIDDoc]]. Notably, a witness receives from the [[ref: DID Controller]] a [[ref: DID
+of a `did:webvh` [[ref: DIDDoc]]. Notably, a witness receives from the [[ref: DID Controller]] a [[ref: DID
 Log]] entry ready for publication, verifies it according to this specification,
 and approves it according to its ecosystem governance (whatever that might be). If the verification and
 approval process results are positive, witnesses returns to the DID Controller a [[ref: Data Integrity]] proof

spec/header.md

@@ -1,13 +1,13 @@
-Trust DID Web - `did:tdw`
+`did:web` + Verifiable History - The `did:webvh` DID Method
 ==================
 
 **Specification Status:** UPDATE IN PROCESS
 
-The `did:tdw` Specification Editors are currently making a combination of
-updates to the DID Method such that this version of the specification has not
-yet been given a version. Once this set of changes have been approved, a version
-will be assigned and it will be the latest version of the specification. Until
-then, those looking for the current version of the specification should review
+The `did:webvh` Specification Editors are currently making a set of
+breaking changes to the DID Method. At this time, the next version of the specification has not
+yet been given a version number. Once the set of changes have been approved, a version
+will be assigned and made the latest version of the specification. Until
+then, those looking for the current stable version of the specification should review
 [v0.4](../).
 
 The updates in process are:
@@ -18,7 +18,7 @@ The updates in process are:
 
 **Current Specification:**- [v0.4](../)
 
-**Specification Version:** To Be Defined (see [Changelog](#didtdw-version-changelog))
+**Specification Version:** To Be Defined (see [Changelog](#didwebvh-version-changelog))
 
 **Source of Latest Draft:**
   [https://github.com/decentralized-identity/trustdidweb](https://github.com/decentralized-identity/trustdidweb)
@@ -27,7 +27,7 @@ The updates in process are:
 - [v0.3](./v0.3)
 
 **Information Site:**
-  [https://didtdw.org/](https://didtdw.org/)
+  [https://didwebvh.info/](https://didwebvh.info/)
 
 **Editors:**
 ~ [Stephen Curran](https://github.com/swcurran)