Adds the technical definition of watchers to the specification

[swcurran]

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:

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

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

[PatStLouis]

Should we only have 1 endpoint defined or have a set of endpoints relevant to their actions? Having only 1 endpoint might overload this endpoint.

The operations a watcher should do can be summed up as:

• Return latest log entry for a given SCID
• Signal a new log entry is available for a given SCID
• Return witness file for a given SCID
• Request witness signature for a given log entry and SCID
  • Only on the case of a witness-watcher
• Return resource for a given SCID and resource path
• Signal new resource for a given SCID and resource path

I would suggest to divide these operations into 3 endpoints to avoid overloading:
<WATCHER URL>/log
<WATCHER URL>/witness
<WATCHER URL>/resource

Operations can be carried as such:

GET <WATCHER URL>/log?scid=<SCID>
Returns latest log entry.

POST <WATCHER URL>/log?scid=<SCID>
Empty body, fetch and update log entries.

GET <WATCHER URL>/witness?scid=<SCID>
Returns witness file.

POST <WATCHER URL>/witness?scid=<SCID>

{
    "logEntry": {...},
    "options": {
        "callbackUrl": "https://..."
    }
}

Validates and signs the log entry provided in request body. This endpoint can return a 200 with the witness proof or a 202 with an empty body, having the proof returned as a POST request to the callbackUrl provided.

GET <WATCHER URL>/resource?scid=<SCID>&path=<resourcePath>
Returns resource

POST <WATCHER URL>/resource?scid=<SCID>&path=<resourcePath>
Fetch and updates resource

[swcurran]

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.