Merge pull request #86 from martipos/clarifications-v2.2

Clarification of content in the overview

spec/overview.md

@@ -1,14 +1,25 @@
 ## Overview
 
-The evolution of [[ref: Decentralized Identifiers]] (DID) continues to
-be a dynamic area of development in the quest for secure and private digital
-identity management. The `did:web` method, praised for its simplicity and ease
-of deployment, allows for DIDs to be associated with a domain's reputation or
-published on platforms such as GitHub. However, it is not without its challenges--
-from trust layers inherited from the web and the absence of a verifiable history
-for the DID. Addressing these concerns, the proposed `did:tdw` (Trust DID Web)
-method aims to enhance `did:web` by introducing a verifiable history feature,
-akin to what is available with ledger-based DIDs, without relying on a ledger.
+The emergence of [[ref: Decentralized Identifiers]] (DIDs) and with them the
+evolution of [[ref: DID Methods]] continues to be a dynamic area of
+development in the quest for trusted, secure and private digital identity
+management where the users are in control of their own data.
+
+The `did:web` method, for example, leverages the Domain Name System (DNS) to
+perform the DID operations. This approach is praised for its simplicity and
+ease of deployment, including DID-to-HTTPS transformation and addressing
+some aspects of trust by allowing for DIDs to be associated with a domain's
+reputation or published on platforms such as GitHub. However, it is not
+without its challenges--
+from trust layers inherited from the web and the absence of a verifiable
+history for the DID.
+
+Tackling these concerns, the proposed `did:tdw` (Trust DID Web)
+method aims to enhance `did:web` by introducing additional features such 
+as a [[ref: self-certifying identifier]] (SCID), update key(s)
+and a verifiable history, akin to what is available with ledger-based DIDs,
+without relying on a ledger.
+
 This approach not only maintains backward compatibility but also offers an
 additional layer of assurance for those requiring more robust verification
 processes. By publishing the resulting DID as both `did:web` and `did:tdw`, it
@@ -22,13 +33,13 @@ The key differences between `did:web` and `did:tdw` revolve around the core
 issues of decentralization and security. `did:web` is recognized for its
 simplicity and cost-effectiveness, allowing for easy establishment of a
 credential ecosystem. However, it is not inherently decentralized as it relies
-on DNS domain names, which require centralized registries, and it lacks a
+on DNS domain names, which require centralized registries. Furthermore, it lacks a
 cryptographically verifiable, tamper-resistant, and persistently stored DID
 document. In contrast, `did:tdw` (Trust DID Web) is proposed as an enhancement
 to `did:web`, aiming to address these limitations by adding a verifiable history
 to the DID without the need for a ledger. This method seeks to provide a more
 decentralized approach by ensuring that the security of the embedded
-self-certifying identifier does not depend on DNS. Additionally, `did:tdw` is
+SCID does not depend on DNS. Additionally, `did:tdw` is
 capable of resolving a cryptographically verifiable trust registry and status
 lists, using DID-Linked Resources, which `did:web` lacks. These features are
 designed to build a trusted web, offering a higher level of assurance for
@@ -47,10 +58,10 @@ The following is a `tl;dr` summary of how `did:tdw` works:
    location as `did:web`'s `did.json` file, and supports an easy transition
    from `did:web` to gain the added benefits of `did:tdw`.
 2. The `did.jsonl` is a list of JSON [[ref: DID log entries]], one per line,
-  whitespace removed (per [[ref: JSON Lines]]), each of which contains the
-  information needed to derive a version of the [[ref: DIDDoc]] from its preceding
-  version.
-3. Each [[ref: log entry]] includes five JSON entries:
+   whitespace removed (per [[ref: JSON Lines]]). Each entry contains the
+   information needed to derive a version of the [[ref: DIDDoc]] from its preceding
+   version. The `did.jsonl` is also referred to as the [[ref: DID Log]].
+3. Each [[ref: DID log entry]] includes a JSON array of five items:
     1. The `versionId` of the entry, a value that combines the version number
        (starting at `1` and incrementing by one per version), a literal dash
        `-`, and a hash of the entry. The [[ref: entry hash]] calculation links each entry
@@ -59,24 +70,27 @@ The following is a `tl;dr` summary of how `did:tdw` works:
     3. A set of `parameters` that impact the processing of the current and
       future [[ref: log entries]].
         - Example [[ref: parameters]] are the version of the `did:tdw` specification and
-        hash algorithm being used.
+        hash algorithm being used as well as the [[ref: SCID]] and update key(s).
     4. The new version of the [[ref: DIDDoc]] as either a `value` (the full document) or
       a `patch` derived using [[ref: JSON Patch]] to update the new version from
       the previous entry.
     5. A [[ref: Data Integrity]] (DI) proof across the entry, signed by a [[ref: DID
       Controller]] authorized to update the [[ref: DIDDoc]], using the `versionId` as the
       challenge.
 4. In generating the first version of the [[ref: DIDDoc]], the [[ref: DID Controller]] calculates
-  the [[ref: SCID]] for the DID, including it as a `parameter` in the first [[ref: log
+  the [[ref: SCID]] for the DID from the entire first [[ref: log entry]] (which
+  includes the [[ref: DIDDoc]]) by adding the string {SCID} everywhere the actual [[ref: SCID]]
+  is to be placed. The [[ref: DID Controller]] then replaces these placeholders
+  with the just calculated [[ref: SCID]], including it as a `parameter` in the first [[ref: log
   entry]], and inserting it where needed in the initial (and all subsequent)
   DIDDocs. The [[ref: SCID]] enables an optional [[ref: portability]] capability, allowing a DID's
   web location to be moved to a new location while retaining the DID and version
   history of the DID.
-5. A [[ref: DID Controller]] generates and publishes the new/updated log file by making it
+5. A [[ref: DID Controller]] generates and publishes the new/updated [[ref: DID Log]] file by making it
   available at the appropriate location on the web, based on the identifier of the
   DID.
 6. Given a `did:tdw` DID, a resolver converts the DID to an HTTPS URL,
-  retrieves, and processes the log file `did.jsonl`, generating and verifying
+  retrieves, and processes the [[ref: DID Log]] `did.jsonl`, generating and verifying
   each [[ref: log entry]] as per the requirements outlined in this specification.
     - In the process, the resolver collects all the [[ref: DIDDoc]] versions and public
       keys used by the DID currently, or in the past. This enables