KERI event stream - events that effect did document key state

spec/diddocuments.md

@@ -2,10 +2,8 @@
 
 ### Introduction
 DID documents in this method are generated or derived from the key state of the
-corresponding AID. If the AID in question is [[ref: non-transferrable]], then the
-DID document is generated algorithmically from the DID value itself, and nothing
-else. If the AID is [[ref: transferrable]], then the [[ref: KEL]] and the [[ref: TEL]]
-are also required inputs to the generation algorithm.
+corresponding AID. By processing the [[ref: KERI event stream]] of the AID, the generation algorithm will be reading the AID [[ref: KEL]] (and possibly [[ref: TEL]])
+to produce the DID document. 
 
 DID documents for this method are pure JSON. They may be processed as JSON-LD by
 prepending an `@context` if consumers of the documents wish.
@@ -15,16 +13,10 @@ is an approach similar to multibase, making them self-describing and terse.
 
 ### DID Document from KERI Events
 The [[ref: KERI event stream]] represents a cryptographic chain
-of custody from the [[ref: AID]] itself down to the current set of signing keys and next rotation key commitments,
-as well as other data such as service endpoints.  When generating a
-DID document an implementation must "walk the [[ref: KEL]]" (follow the chain of key events) to determine the current key state.  Due to the fact that the KERI protocol
-allows for non-establishment event (events that don't change key state) to be intermixed in a [[ref: KERI event stream]] with establishment
-events (those that change key state), the last event may not be an establishment event and thus can not be relied on to
-provide key information.  In addition, the current set of witnesses is calculated from the initial set declared in the
-inception event and "adds" and "cuts" declared in rotation events.
+of custody from the [[ref: AID]] itself down to the current set of keys and the cryptographic commitment to the next rotation key(s). The [[ref: KERI event stream]] also contains events that do not alter the [[ref: AID]] key state, but are useful for the DID document, such as the supported domains, current set of service endpoints, etc. A did:webs resolver produces the DID document by processing the [[ref: KERI event stream]] to determine the current key state. We detail the different events in (KERI event details)[#KERI-event-details] below and show how they change the DID Document. The mapping from [[ref: KERI event stream]] to the properties of the DID Document is the core of the did:webs resolver logic. There are many ways to receieve the [[ref: KERI event stream]], but only one way to process a [[ref: KERI event stream]] to produce the verifiable DID document. Understanding the optimal way to retrieve the [[ref: KERI event stream]] is beyond the scope of the spec, but a reference implementation of the resolver that details these techniques is being developed alongside this spec. The important concepts are that the entire [[ref: KERI event stream]] is used to produce and verify the DID document.
 
-In KERI the calculated values that result from walking the [[ref: KEL]] are referred to as the "current key state" and expressed
-in the Key State Notice (KSN) record.  An example of a KSN can be seen here:
+In KERI the calculated values that result from processing the [[ref: KERI event stream]] are referred to as the "current key state" and expressed
+in the Key State Notice (KSN) record.  An example of a KERI KSN record can be seen here:
 
 ```json
 {
@@ -226,12 +218,12 @@ For example, a KERI AID with only the following inception event in its KEL:
 ```
 
 #### Verification Relationships
-KERI AID public keys can be used to sign a variety of data.  This includes but is not limited to logging into a website, challenge-response exchanges and credential issuances.  It follows that for each public key in `k` two verification relationships must be generated in the DID document.  One verification relationship of type `authentication` and one verification relationship of type `assertionMethod`.  The `authentication` verification relationship defines that the DID controller can authenticate using each key and the `assertionMethod` verification relationship defines that the DID controller can express claims with each key (should we address multisig and thresholds here?).
+KERI AID public keys can be used to sign a variety of data.  This includes but is not limited to logging into a website, challenge-response exchanges and credential issuances.  It follows that for each public key in `k` two verification relationships must be generated in the DID document.  One verification relationship of type `authentication` and one verification relationship of type `assertionMethod`.  The `authentication` verification relationship defines that the DID controller can authenticate using each key and the `assertionMethod` verification relationship defines that the DID controller can express claims with each key (TODO: address multisig and thresholds).
 
 References to verification methods in the DID document MUST use the relative form of the identifier, e.g., `"authentication": ["#<identifier>"]`.
 
 #### Service Endpoints
-In KERI, service endpoints are defined by 2 sets of signed data that follow the Best Available Data - Read, Update, Nullify (BADA-RUN) (ref?) rules for data processing.  Detailing the rules of BADA-RUN is beyond the scope of this document but to summarize, the protocol ensures that all data is signed in transport and at rest and versioned to ensure only the latest signed data is available.
+In KERI, service endpoints are defined by 2 sets of signed data that follow the Best Available Data - Read, Update, Nullify ([[ref: BADA-RUN]]) rules for data processing.  The protocol ensures that all data is signed in transport and at rest and versioned to ensure only the latest signed data is available.
 
 The two data sets used to define service endpoints are called Location Schemes and Endpoint Role Authorizations and are expressed in KERI `rpy` events.  Location Schemes define URLs for any URL scheme that an AID has exposed.  For example, the following `rpy` method declares that the AID `EIDJUg2eR8YGZssffpuqQyiXcRVz2_Gw_fcAVWpUMie1` exposes the URL `http://localhost:3902` for scheme `http`:
 
@@ -288,7 +280,7 @@ The current set of endpoint roles in KERI is contained in the following table:
 
 
 ##### KERI Service Endpoints as Services
-As defined above in [KERI Service Endpoints](#KERI-Service-Endpoints) service endpoints roles beyond `witness` can be defined using Location Scheme and Endpoint Authorization records in KERI.  This section will map the current roles in KERI to service `type` values in resulting DID documents and propose a new role in KERI to map to the existing `DIDCommMessaging` service type declared in DID Specification Registries (ref?).
+As defined above in [KERI Service Endpoints](#KERI-Service-Endpoints) service endpoints roles beyond `witness` can be defined using Location Scheme and Endpoint Authorization records in KERI.  This section will map the current roles in KERI to service `type` values in resulting DID documents and propose a new role in KERI to map to the existing [DIDCommMessaging](https://www.w3.org/TR/did-spec-registries/#didcommmessaging) service type declared in DID Specification Registries.
 
 ```json
 {
@@ -314,7 +306,7 @@ TODO:  Detail the transformation
 
 
 #### Other Key Commitments
-Data structures similar to Location Scheme and Endpoint Authorizations and managed in KERI using BADA-RUN could be created that would be used for declaring other types of keys, for example encryption keys, etc
+Data structures similar to Location Scheme and Endpoint Authorizations and managed in KERI using [[ref: BADA-RUN]] could be created that would be used for declaring other types of keys, for example encryption keys, etc
 
 TODO:  Propose new data structures in KERI and Detail the transformation
 
@@ -500,3 +492,18 @@ Resulting DID document:
   ]
 }
 ```
+
+### Basic KERI event details
+[DID Document from KERI Events](#did-document-from-keri-events) introduced the core [[ref: KERI event stream]] and related DID Document concepts. This section provides additional details regarding the basic types of KERI events and how they relate to the DID document.
+
+#### Key state events
+When processing the [[ref: KERI event stream]] there are two broad types of key state events (KERI parlance is 'establishment events') that can alter the key state of the DID document.  Every [[ref: AID]] starts with an [[ref: inception event]]. If that inception event does not commit to a future set of rotation key hashes, then the AID is non-transferrable because the identifier can never change key state. If the inception event does commit to a future set of rotation key hashes, then the AID is transferrable and there could be future rotation events that transfer the key state from the current keys to the rotation keys that were committed to in the previous key state event.
+* [[def: Inception event]]: The inception event is the first event in the [[ref: KEL]] that establishes the AID. This defines the initial key set and if the controller(s) desire future key rotation (transfer) then the inception event must commit to a set of future rotation key hashes. When processing the [[ref: KERI event stream]], if there are no rotation events after the inception event, then this is the current key state of the AID and will be reflected in the DID Document as specified in [Verification Methods](#verification-methods) and [Verification Relationships](#verification-relationships). You can learn more about the inception event in the [KERI specification](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#name-basic-terminology) and you can see an [example inception event](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#name-inception-event). To learn about future rotation key commitment, see the sections about [pre-rotation](#pre-rotation) and the [KERI specification section on pre-rotation](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#name-key-pre-rotation-concept)
+* [[def: Rotation event]]: Rotation events come after inception events and can only change the key state to the previously committed to rotation keys and if the controller(s) desires future key rotation (transfer) then the rotation event must commit to a set of future rotation key hashes. When processing the [[ref: KERI event stream]], if there are rotation events after the inception event, then the last rotation event is the current key state of the AID and will be reflected in the DID Document as specified in [Verification Methods](#verification-methods) and [Verification Relationships](#verification-relationships). You can learn more about rotation events in the [KERI specification](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#name-basic-terminology) and you can see an [example rotation event](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#name-rotation-event-message-body). To learn about future rotation key commitment, see the sections about [pre-rotation](#pre-rotation) and the [KERI specification section on pre-rotation](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#name-key-pre-rotation-concept)
+
+### Delegation KERI event details
+This section focuses on delegation relationships between KERI AIDs. [DID Document from KERI Events](#did-document-from-keri-events) introduced the core [[ref: KERI event stream]] and related DID Document concepts. This section provides additional details regarding the basic types of KERI events and how they relate to the DID document. [Basic KERI event details](#basic-keri-event-details) provides additional details on the basic types of KERI events and how they relate to the DID document.
+
+#### Delegation key state events
+* [[def: Delegated inception event]]: Establishes a delegated identifier for which either the delegator or the delegate can end the delegation commitment. All delegation relationships start with a delegated inception event. The KERI specification provides [an example of a delegated inception event](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#name-delegated-inception-event-m).
+* [[def: Delegated rotation event]]: Updates the delegated identifier commitment. Either the delegator or the delegate can end the delegation commitment. Any change to the [[ref: Delegated inception event]] key state or delegated rotation event key state requires a delegated rotation event. The KERI specification provides [an example of a delegated rotation event](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#section-8.2)

spec/keri.md

@@ -25,7 +25,7 @@ The simplest AIDs (called [[ref: direct mode]] AIDs in KERI) have no additional
 
 [[def: Pre-rotation]]
 
-Optionally, the inception event of an AID can also reference the hash of the _next_ key that will be used to control the AID. This changes how the AID is derived: `derive( initial_public_key, next_key_hash )`. KERI calls this feature [[ref: pre-rotation]]; AIDs that use it are called [[ref: transferrable]] AIDs because their control can be transferred to new keys. AIDs that do not use pre-rotation cannot change their keys, and are thus thus [[ref: non-transferrable]].
+Optionally, the inception event of an AID can also reference the hash of the _next_ key that will be used to control the AID. This changes how the AID is derived: `derive( initial_public_key, next_key_hash )`. KERI calls this feature [[ref: pre-rotation]]; AIDs that use it are called [[ref: transferrable]] AIDs because their control can be transferred to new keys. AIDs that do not use pre-rotation cannot change their keys, and are thus [[ref: non-transferrable]].
 
 Pre-rotation has profound security benefits. If a malicious party steals the private key for an AID with this feature, they only accomplish _temporary_ mischief, because the already-existing KEL contains a commitment to future state. This prevents them from rotating the stolen AID's key to an arbitrary value of their choosing. As soon as the AID owner suspects a compromise, they can do a valid rotation that locks the attacker out again.
 
@@ -56,4 +56,6 @@ KERI uses [[[ref: CESR]] ](https://weboftrust.github.io/ietf-cesr/draft-ssmith-c
 *   JSON, CBOR, and MsgPack are all valid and equivalent ways to represent a KERI data structure. Further, JSON, CBOR, and MsgPack can be freely mixed/combined, because CESR makes each chunk of content self-describing, _and a digital signature on a CESR data structure is stable no matter which format is used_. The practical effect is that developers get the best of both worlds: they can produce and consume data structures mostly using whatever toolset they like, they can displayed and debug data structures in a human-friendly form, and they can store or transmit data in its tersest form, _all without changing the signature_.
 *   Cryptographic primitives such as keys, hashes, and signatures are structured strings with a recognizable data type prefix and a standard representation. This means they are very terse, and there is no need for the variety of representation methods that create interoperability challenges in other DID methods (`publicKeyJwk` versus `publicKeyMultibase` versus other; see [section 5.2 of the DID spec](https://www.w3.org/TR/did-core/#verification-material)).
 
-Despite this rich set of features, KERI imposes only light dependencies on developers. The cryptography it uses is familiar and battle-hardened — exactly what you'd find in standard toolkits for big numbers and elliptic curves. For example, the python implementation uses just the `pysodium`, `blake3`, and `cryptography` packages. Libraries for KERI exist in javascript, rust, and python.
+Despite this rich set of features, KERI imposes only light dependencies on developers. The cryptography it uses is familiar and battle-hardened — exactly what you'd find in standard toolkits for big numbers and elliptic curves. For example, the python implementation uses just the `pysodium`, `blake3`, and `cryptography` packages. Libraries for KERI exist in javascript, rust, and python.
+
+In this spec we generically refer to the CESR event stream of KEL and TEL events as the [[ref: KERI event stream]] which is used to verify the did:webs DID document.

spec/terminology.md

@@ -16,4 +16,4 @@
 ~ As defined by KERI.
 
 [[def: KERI event stream, KERI event streams]]
-~ A stream of verifiable KERI data, consisting of the [[ref: key event log]] ([[ref: KEL]]) and other data such as [[ref: transaction event log]] ([[ref: TEL]]). This data may be serialized in a file using [[ref: CESR]] encoding.
+~ A stream of verifiable KERI data, consisting of the [[ref: key event log]] ([[ref: KEL]]) and other data such as [[ref: transaction event log]] ([[ref: TEL]]). This data is a [[ref: CESR]] Event stream (TODO: link to IANA application/cesr media type) and may be serialized in a file using [[ref: CESR]] encoding. We refer to these CESR stream resources as KERI event streams to simplify the vocabulary.