Merge pull request #27 from swcurran/spec-updates

Add DID URL and /whois resolution sections

spec/abstract.md

@@ -1,37 +1,27 @@
 ## Abstract
 
-`did:web` a useful, simple DID Method that makes deployment easy, and can be
-used to build beautifully on a domain's existing reputation -- or even be
-published content publishing platforms such as GitHub. But `did:web` also
-inherits some of the security flaws of the Web and lacks a specified way to access the
-history of the DID--features that created the initial excitement around
-ledger-based DIDs. For something as important as cryptographic key publishing,
-those missing features can be a problem.
+The evolution of Decentralized Identifiers (DIDs) 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 like GitHub. However, it is not without its challenges, particularly concerning security vulnerabilities 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 the `did:web` by introducing a verifiable history feature, akin to what is available with ledger-based DIDs, but crucially, 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 caters to a broader range of trust requirements, from those who are comfortable with the existing `did:web` infrastructure to those seeking greater security assurances provided by `did:tdw`. This innovative step represents a significant stride towards a more trusted and secure web, where the integrity of cryptographic key publishing is paramount.
 
-We propose a new DID Method that compliments `did:web` that, with a relatively
-simple set of dependencies and processing steps, adds a fully verifiable history
-to a web-based DID such as one might get from a ledger-based DID, but without
-the ledger. For backwards compatibility, and for verifiers that just "trust"
-`did:web`, the resulting DID can be published as a `did:web` in parallel. For
-resolvers that want more assurance, `did:tdw` (Trust DID Web) provides a way to
-"trust did:web" (or to enable a "trusted web" if you say it fast), by supporting
-these features:
+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 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` offers 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 cryptographic key publishing and management.
 
-- Publishing of all DID Document (DIDDoc) versions for a DID instead of, or beside, a `did:web` DID.
+For backwards compatibility, and for verifiers that just "trust" `did:web`, a `did:tdw` can be trivially modified and published in parallel as a `did:web` DID. For resolvers that want more assurance, `did:tdw` provides a way to "trust did:web" (or to enable a "trusted web" if you say it fast), by supporting these features:
+
+- Ongoing publishing of all DID Document (DIDDoc) versions for a DID instead of, or beside, a `did:web` DID.
 - Uses the same DID-to-HTTPS transformations as `did:web`.
-- Provides resolvers with the full history of the DID via a verifiable chain of
-  updates to the DIDDoc from creation to the latest update.
+- Provides resolvers the full history of the DID using a verifiable chain of
+  updates to the DIDDoc from creation to the current update.
 - A [[def: self-certifying identifier]] (SCID) for the DID that is globally unique and
   derived from the initial DIDDoc, enabling verifiable "alsoKnownAs" DIDs.
-- Each DIDDoc update includes a proof signed by the DID Controller(s) authorized
+- DIDDoc updates include a proof signed by the DID Controller(s) authorized
   to update the DID.
 - An optional mechanism for publishing "pre-rotation" keys to prevent loss of
   control of the DID in cases where an active private key is compromised.
-- A DID Method-specific (but useful for other DID Methods) approach to
-  publishing documents (files, verifiable credentials, verifiable presentations,
-  etc.) via the DID URL path. For example, a company can publish a verifiable
-  credential rendering package as a JWS signed by the issuer's DID and at the
-  URL `<did>/path/to/render_credential.jws`.
+- DID URL path handling that defaults to automatically resolving a
+  `<did>/path/to/file` being retrieved through using a comparable DID-to-HTTPS
+  translation as for the DIDDoc.
+- A DID URL path `<did>/whois` that defaults to automatically returning a [[ref:
+  Verifiable Presentation]] containing [[ref: Verifiable Credentials]] with the
+  DID as the `credentialSubject`, signed by the DID.
 
 The following is a `tl;dr` summary of the specification summarizing how `did:tdw` works.
 
@@ -40,19 +30,18 @@ The following is a `tl;dr` summary of the specification summarizing how `did:tdw
 - The `didlog.txt` is a list of JSON [[ref: DID log entries]], one per line,
   whitespace removed, each of which contains the information needed to derive a
   version of the DIDDoc from its preceding version.
-- Each entry includes JSON entries containing:
-  - A hash of the entry.
-  - The `versionId` of the DIDDoc, starting from 1 and incrementing.
-  - The `versionTime` (as stated by the DID Controller) of the entry.
-  - A set of `parameters` that impact the processing of the current and
+- Each entry includes six JSON entries:
+  1. A hash of the entry.
+  2. The `versionId` of the DIDDoc, starting from 1 and incrementing.
+  3. The `versionTime` (as stated by the DID Controller) of the entry.
+  4. A set of `parameters` that impact the processing of the current and
     future log entries.
-    - Examples parameters are the version of the `did:tdw` specification
-      and the hash algorithm being used by the controller. All available parameters are
-      defined in this specification.
-  - The new version of the DIDDoc as either a `value` (the full document) or a
+       - Example parameters are the version of the `did:tdw` specification
+      and hash algorithm being used.
+  5. The new version of the 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.
-  - A [[ref: Data Integrity]] (DI) proof across the entry, signed by a DID
+  6. A [[ref: Data Integrity]] (DI) proof across the entry, signed by a DID
     Controller authorized to update the DIDDoc.
 - In generating the first version of the DIDDoc, the DID Controller calculates
   the [[ref: SCID]] for the DID, includes it as a `parameter` in the first log entry, and
@@ -70,8 +59,8 @@ The following is a `tl;dr` summary of the specification summarizing how `did:tdw
   can verify the DIDDoc, if wanted).
   - Of course, a resolver settling for just the `did:web` version of the DID
     does not get the verifiability of the `did:tdw` log.
-- `did:tdw` DID URLs with paths can be resolved to documents published by the
-  DID Controller.
+- `did:tdw` DID URLs with paths and `/whois` are resolved to documents published by the
+  DID Controller by default in the web location relative to the `didlog.txt` file.
 
 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.

spec/example.md

@@ -197,7 +197,7 @@ The same content as it is found in the `didlog.txt` file:
 #### `did:web` Version of DIDDoc
 
 As noted in the [publishing a parallel `did:web`
-version]()(#publishing-a-parallel-didweb-did) of the DIDDoc section of this
+version](#publishing-a-parallel-didweb-did) of the DIDDoc section of this
 specification, here is what the `did:web` DIDDoc looks like for the `did:tdw`
 above.
 

spec/header.md

@@ -1,7 +1,7 @@
 Trust DID Web - `did:tdw`
 ==================
 
-**Specification Status:** v1.0
+**Specification Status:** DRAFT
 
 **Latest Draft:**
   [https://github.com/bcogv/trustdidweb](https://github.com/bcogv/trustdidweb)