Adds the technical definition of watchers to the specification #181

swcurran · 2025-03-04T23:30:53Z

Adds the concept of watchers to the spec. As always, provides a relatively short/simple technical implementation, and leaves the governance / implementation details out of the spec. That said, it does add more implementation details than, say, the witness implmentation.

Watchers are a list of URLs that monitor the DID. The URL must respond to a core set of 5 endpoints to return the cached DID Log, return the cached witness.json file, return a cached resource, webhook about an update to the DID, webhook about an update to a resource.

It's a slippery slope to define how much to include.

Questions from me:

Feedback on what is there so far?
What details need to be added about the list as DID Metadata?
Should the webhooks have an attached proof for "authorization"?

Signed-off-by: Stephen Curran [email protected]

Signed-off-by: Stephen Curran <[email protected]>

spec/specification.md

Signed-off-by: Stephen Curran <[email protected]>

swcurran · 2025-03-14T22:17:49Z

Updated the PR to add items discussed at the 2025-03-13 Meeting. Notably:

Added a "DELETE" endpoint that requests removal of a SCID from the watcher's cache -- governance outside of this specification.
Added that all POST and DELETE must respond to the successful receipt of a message with a 202, indicating asynchronous processing will occur. This eliminates the possiblity of a POST of the entry for a witness responding in any way other than via the callback.
Added that the URLs can be any type, and that if they are HTTP(S) URLs, they MUST adhere to the defined endpoints.

Not done yet:

attach an OpenAPI definition of the API (@PatStLouis ?)
define if/how any of the POSTs can/should be associated with the DID Controller -- a proof and if so the impact on the API. For example, should a DELETE have to have a proof, if it is possible that the DID Controller no longer exists? Which is of course, back to governance.
anything for the sender about POSTs/DELETE if a 202 is not received -- e.g. retries, etc.

…version of the specification and includes the OpenAPI yml definition Signed-off-by: Stephen Curran <[email protected]>

Signed-off-by: Stephen Curran <[email protected]>

brianorwhatever · 2025-03-28T17:57:50Z

spec/specification.md

@@ -1027,7 +1030,8 @@ has the following data structure:
  "threshold": n,
  "witnesses" : [
      {
-         "id": "<did:key DID of witness>"
+         "id": "<did:key DID of witness>",
+         "watcherURL": "<URL>"


here we have the watcher URL in the witness but above there is a watchers array. I'm confused on this is this intended mixing witnesses and watchers feel strange to me.

The idea is that if a witness is a watcher, we want the resolver to know that as it provides additional metadata about who the witness is that can be helpful for governance (which is outside the scope of the spec.). The DID Controller also uses that with the “watcher API” that it can send the witness a notification of a new entry before it is published, to allow getting back a witness proof. I think it is logical that a witness for a DID also be a watcher and so we should encourage it and tie the two together.

That said, it does add a bit of complication, and I’m not 100% tied to it. I can see removing that and the watcher entry notification API endpoint.

I don't know if tying the two concepts together this tightly makes sense although I do understand the desire to have a URL for a witness. I don't think cheating and calling it a watcherURL is the way 😄

brianorwhatever · 2025-03-28T17:59:19Z

spec/specification.md

+[[ref: Watchers]] are components found in some digital trust and DID ecosystems that monitor DIDs on behalf of clients for various purposes, such as:
+
+- **Caching verified DIDs:** Storing verified DID documents to facilitate efficient resolution.
+- **Ensuring persistence:** Maintaining access to DIDs even after removal by the [[ref: DID Controller]]. For example, the [Verifiable Data Gateway](https://github.com/LedgerDomain/did-webplus?tab=readme-ov-file#verifiable-data-gateway-vdg) in [did](https://github.com/LedgerDomain/did-webplus/blob/main/README.md)[:webplus](https://github.com/LedgerDomain/did-webplus/blob/main/README.md) could function as a [[ref: watcher]] for enduring DIDs.


I don't know if the reference to did:webplus is a good idea it might confuse people

Reasonable. My hope was that the it would encourage the did:webplus folks to formalize their VDG as a watcher as we have defined it. It’s non-normative, so not a spec issue.

brianorwhatever · 2025-03-28T18:03:26Z

spec/specification.md

+
+did:webvh provides two mechanisms for notifying resolvers (and their clients via [[spec:DID-RESOLUTION]] metadata) about configured [[ref: watchers]]:
+
+1. Witness-watchers: A [[ref: witness]] **MAY** also act as a [[ref: watcher]], indicated by the watcherURL attribute in the witnesses [[ref: parameter]]. If a [[ref: witness]] is removed, it ceases to be a [[ref: watcher]].


Why have the differences? Can't a witness watcher euro just be put into the standalone watchers?

It can — it just has to be done explicitly. If the witness is dropped, they are removed from the witness and the (implied) witness-watcher list. If the DID Controller redefines the watcher list with that watcher, that’s fine.

It feels like we have three different concepts now

a witness

a witness-watcher

a watcher

Yes. But for the reasons given, that second category is useful.

Maybe 1 isn't then? This comes back to the question about how to get a proof from a witness. Previously, we had said this was out of spec and now we sort of have this in spec in the second category, but not in the first category.

Interesting idea…requiring that all witnesses be a watcher and provide a Watcher URI? Others?

Strong -1 from me, as we have significant work done with the didcomm witness protocol and this would effectively scrap the current did webvh server work and acapy witnessing work.

It's not clear to me where the desire to have an endpoint to get a witness signature in the log file comes from. Who does this benefit? Surely the controller already knows how to get a witness signature prior to adding this witness to an entry. The witness parameter is there for resolvers to ensure the log has been properly witnessed.

We can leave it off — it was a bit of throw in and perhaps not well thought out.

It has value in that it defines an optional way to retrieve a witness proof. A DID Controller/Witness is not forced to use it if the witness is also a watcher — it is just possible. So the approach you are using is completely valid. It is just that since we have this option, it can be used. That said, we can remove it from the Watcher spec, and a DID Controller can have its witnesses use such as endpoint.

As I write this, I think it is best that we drop it from the spec — it is not obvious why it is there. I’ll remove it, and let’s add an article to the information site about the different ways DID Controllers and Witnesses can interact — including what you have done, @PatStLouis and this approach.

brianorwhatever · 2025-03-28T18:04:32Z

spec/specification.md

+1. Witness-watchers: A [[ref: witness]] **MAY** also act as a [[ref: watcher]], indicated by the watcherURL attribute in the witnesses [[ref: parameter]]. If a [[ref: witness]] is removed, it ceases to be a [[ref: watcher]].
+2. Standalone watchers: The watchers [[ref: parameter]] lists URIs that identify independent [[ref: watchers]].
+
+Watcher URIs MAY use schemes other than HTTP(S), such as a DID ([[spec:DID-CORE]]), depending on the specific implementation or network requirements. However, this specification does not define how non-HTTP(S) [[ref: watcher]] URIs should be resolved or interacted with. If a [[ref: watcher]] uses an HTTP(S) URL, it **MUST** support the HTTP-based interaction model defined in the [Watcher Endpoints and Behavior](#watcher-endpoints-and-behavior) section.


this added complexity is it worth it?

See comment above. In the calls we’ve had and where this was explained, no one said anything against it…

Sorry, I wasn't very clear here. I'm at the added complexity of allowing DID URIs. I think we should just focus on HTTP or else we have a ton of interoperability questions that open up

That was guidance from the Work Item group (looking at @andrewwhitehead :smiling). The directive I received was to say that URIs were valid, but to provide API details only if the URI was an HTTP URL. Leaves the door open for someone defining (for example) a watcher with a DID URI and services for the Watcher endpoints. But we definitely don’t want to put that into the spec.

spec/specification.md

PatStLouis · 2025-03-31T14:49:12Z

watcherOpenAPI/watcher-v1.0.0.yml

+        '200':
+          description: successful operation
+          content:
+            text/jsonl:


jsonl support for openapi is being discussed, there's no clear way to define it at the moment besides documenting it.

We have this in the spec, The content type for the did.jsonl file SHOULD be text/jsonl., so I think the OpenAPI spec should say that. If not that, any suggestions?

yes I think that's good

I took some text from the spec and suggested a description for the response

…atcher section Signed-off-by: Stephen Curran <[email protected]>

swcurran · 2025-03-31T16:15:04Z

@PatStLouis -- removed the witness entry request from the API. I think I got the OpenAPI right. Please review.

PatStLouis

Some small tweaks

watcherOpenAPI/watcher-v1.0.0.yml

Co-authored-by: Patrick St-Louis <[email protected]> Signed-off-by: Stephen Curran <[email protected]>

Signed-off-by: Stephen Curran <[email protected]>

Adds the technical definition of watchers to the specification

a67afdc

Signed-off-by: Stephen Curran <[email protected]>

swcurran requested review from a team March 4, 2025 23:31

Merge branch 'main' into watcherURLs

bff1dca

PatStLouis reviewed Mar 11, 2025

View reviewed changes

spec/specification.md Outdated Show resolved Hide resolved

swcurran added 3 commits March 11, 2025 15:16

Merge branch 'main' into watcherURLs

5ab7156

Updates the new watchers section based on feedback

8f8b3f0

Signed-off-by: Stephen Curran <[email protected]>

Updates for DELETE, 202 Responses and non-HTTPs URLs

5d26d11

Signed-off-by: Stephen Curran <[email protected]>

swcurran added 3 commits March 26, 2025 16:29

Updates the Watcher API section to reference an OpenAPI file for the …

f815dfa

…version of the specification and includes the OpenAPI yml definition Signed-off-by: Stephen Curran <[email protected]>

Updates to the Watchers section from feedback

7e067e1

Signed-off-by: Stephen Curran <[email protected]>

Fix up the OpenAPI YML Definition based on feedback

d761cb1

Signed-off-by: Stephen Curran <[email protected]>

brianorwhatever reviewed Mar 28, 2025

View reviewed changes

Merge branch 'main' into watcherURLs

b295bb6

PatStLouis reviewed Mar 31, 2025

View reviewed changes

Remove witness entry request from Watcher API, minor adjustments to W…

96dba3b

…atcher section Signed-off-by: Stephen Curran <[email protected]>

PatStLouis requested changes Mar 31, 2025

View reviewed changes

watcherOpenAPI/watcher-v1.0.0.yml Outdated Show resolved Hide resolved

watcherOpenAPI/watcher-v1.0.0.yml Show resolved Hide resolved

watcherOpenAPI/watcher-v1.0.0.yml Outdated Show resolved Hide resolved

swcurran and others added 7 commits March 31, 2025 15:46

Update watcherOpenAPI/watcher-v1.0.0.yml

208aaa1

Co-authored-by: Patrick St-Louis <[email protected]> Signed-off-by: Stephen Curran <[email protected]>

Update watcherOpenAPI/watcher-v1.0.0.yml

5b22299

Co-authored-by: Patrick St-Louis <[email protected]> Signed-off-by: Stephen Curran <[email protected]>

Update watcherOpenAPI/watcher-v1.0.0.yml

dd7195b

Co-authored-by: Patrick St-Louis <[email protected]> Signed-off-by: Stephen Curran <[email protected]>

Update abstract.md after other updates

e486ff3

Signed-off-by: Stephen Curran <[email protected]>

Remove conflict line about errors

5c0edb9

Signed-off-by: Stephen Curran <[email protected]>

Merge branch 'main' into watcherURLs

ce6f258

Signed-off-by: Stephen Curran <[email protected]>

Remove blank line

ed8b0ab

Signed-off-by: Stephen Curran <[email protected]>

PatStLouis previously approved these changes Apr 1, 2025

View reviewed changes

Removes the concept of a witness-watcher

8aedda3

Signed-off-by: Stephen Curran <[email protected]>

swcurran dismissed PatStLouis’s stale review via 8aedda3 April 1, 2025 18:30

swcurran added 2 commits April 1, 2025 11:33

Fix typo in JSON

f96c33d

Signed-off-by: Stephen Curran <[email protected]>

Typo

89694d1

Signed-off-by: Stephen Curran <[email protected]>

swcurran requested review from brianorwhatever and PatStLouis April 1, 2025 18:35

PatStLouis approved these changes Apr 2, 2025

View reviewed changes

swcurran merged commit 2a8eef9 into decentralized-identity:main Apr 3, 2025
1 check passed

swcurran deleted the watcherURLs branch April 23, 2025 19:54


		did:webvh provides two mechanisms for notifying resolvers (and their clients via [[spec:DID-RESOLUTION]] metadata) about configured [[ref: watchers]]:

		1. Witness-watchers: A [[ref: witness]] MAY also act as a [[ref: watcher]], indicated by the watcherURL attribute in the witnesses [[ref: parameter]]. If a [[ref: witness]] is removed, it ceases to be a [[ref: watcher]].

Adds the technical definition of watchers to the specification #181

Adds the technical definition of watchers to the specification #181

Uh oh!

Conversation

swcurran commented Mar 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

swcurran commented Mar 14, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

swcurran commented Mar 31, 2025

Uh oh!

PatStLouis left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

swcurran commented Mar 4, 2025 •

edited

Loading