Discovery Refactoring - Derived from JOSE replacement

[CMCDragonkai]

Specification

This spec is less well-baked compared to the GestaltGraph because this is my initial review of the discovery domain.

The discovery domain depends on:

1. NodeManager for connecting to nodes and asking about their sigchain
2. TaskManager to run background tasks
3. GestaltGraph to update the links they discover
4. KeyRing to know if we are finding our own NodeId.
5. Sigchain to add its own sigchain into the GestaltGraph

There are several major changes here required:

GestaltId instead of GestaltKey

The GestaltGraph now uses GestaltId, it does not expose the GestaltKey, all operations must now use the GestaltId when interacting with the Sigchain.

Querying the Sigchain of remote node

When connecting to the remote node in order to discover their sigchain, it must be understood as a stream of claims. Rather than one giant claim array. This means instead of calling NodeManager.requestChainData, it should be using the NCM and connecting to it.

We know that the NCM is a supervisor over node connection pools. It should be the primary way by which downstream domains attempt contact to other nodes and to call them.

The NM by contrast can also use the NCM and expose a variety of high-level functionality over the nodes. However in this case, the only user of NodeManager.requestChainData is the Discovery and it makes more sense for the Discovery to directly operate the NodeConnection and its encapsulated GRPC client.

Therefore the Discovery should be relying on the NodeConnectionManager and not the NodeManager.

On the GRPC service handler, the nodesChainDataGet should be changed to a server stream. This stream will yield SignedClaim.

On the other side, when querying the own Sigchain, it should not just call Sigchain.getClaims, but get only the "latest" (and unrevoked) claim per node ID or identity ID. To do this, the Sigchain will need some sort of indexing to keep track of this (#327).

Processing own Node

With respect to #319, it should be processing its own sigchain immediately on start and adding such data to the GestaltGraph.

The Sigchain can be mutated by itself during the claiming process for node to node and node to identity. This claiming process cannot be initiated by the Sigchain.

This part is currently a bit confusing.

For node to node claims, this all starts in NodeManager.claimNode, which itself ends up calling the Sigchain.

But for node to identity claims, this is done by the GRPC handler identitiesClaim which orchestrates operations between the Sigchain and Provider.

We need to clarify on a few things here:

1. Should the Discovery be responsible for managing the node's own Sigchain and putting its data into the GestaltGraph?
2. How should the Discovery crawl its GestaltGraph and does it also try to discover its own vertex?
3. We decided long ago, that GRPC handlers (service layer) should be thin wrappers around domain models (business layer) doing the bulk of the business logic. This means claiming an identity should be in the identities domain just like claiming a node is in the nodes domain.
4. The Sigchain is not aware of the GestaltGraph and the GestaltGraph is not aware of the Sigchain. This is good, because we can do object composition here. Given that any claiming process will involve the Sigchain, should the GestaltGraph also be updated by the claiming process?

Here's one possible answer to the question:

Here you can see that claiming an identity or a node is what ends up updating the GestaltGraph. It's not a reactive thing, because claiming updates both our own Sigchain and our own gestalt in the GestaltGraph.

The claimNode and claimIdentity are now part of the domain models. In the case of claimIdentity, this needs to be part of the Provider. In fact, as an abstract class, we would expect that these dependencies to be injected into the Provider for it to be used during the claiming process. This may not be entirely good design if we expect provider plugins. In the case of plugins, we have 2 choices, we are either calling into it, or it is calling into us. If we give it the Sigchain and GestaltGraph, we are giving it quite a lot of power, thus allowing it to call into us, is like providing an entire scripting environment. A safer model is that we call into it. In that case, it would be part of the IdentitiesManager.

Note that the diagram above renames IdentitiesManager as ProviderManager atm because it doesn't do anything except manager Provider. But if the claiming process is a "don't call us, we'll call you", then it can be left as IdentitiesManager.

Finally Discovery does not actually need access to the Sigchain nor to the KeyRing. The discovery does not need discover its own node, because any changes to its own node's gestalt would be reflected immediately during the claimNode and claimIdentity operations. The discovery only needs to discover the node's own neighbours, which can it do by querying the gestalt graph and prioritising based on TTLs (which are yet to be implemented). There are still some questions as to how does the discovery become aware about the new nodes in the gestalt? This can either be push-based or pull-based. I believe right now it is pull-based, which means there's a timer-based polling onto the GestaltGraph and we have talked about making the Discovery reactive to the GestaltGraph.

Deliberate Operations for Discovery

It needs to be reviewed how exactly users can directly tell the Discovery to start its discovery process against a given NodeId or ProviderIdentityId.

GestaltLinkNode for doubly signed claims

See: #493 (comment)

Notifications for Claiming Nodes

See: #493 (comment)

Additional context

• Replace JOSE with our own tokens domain and specialise tokens for Sigchain, Notifications, Identities and Sessions #481
• Add priority and TTL to Discovery process #462
• Write tests to cover all possible states of the Discovery, NodeConnection, and discovered Node during the discovery process #349
• Adding and maintaining own Gestalt in Gestalt Graph #319
• Add the ability to search across Disconnected Identities during Social Discovery #330

Tasks

1. 1. Replace GestaltKey usage with GestaltId.
2. 2. Discovery logic needs to refactored and cleaned up
3. 3. Streaming claims when connecting to remote nodes and identities.
4. 4. Don't process your own node, It should be added to the GestaltGraph when claims are made. This is done for both claim node and claim identity.
5. 5. claimNode needs to be a part of the nodes domain along with the handler logic for it. The logic behind this needs to be refactored to use the new claims/token changes.
6. 6. Likewise the claimIdentity logic and handler needs to be apart of the IdentityManager or Provider.
7. 7. Existing tests need to be updated and coverted to using fast check.
8. 8. New test needs to be created to do a more complex model based testing using all of the available Discovery commands.
9. 9. Index claim read, when requesting claims we can request only the claims newer that the provided Id.
10. 10. Notifications needs to be updated to make use of the new tokens. \
11. Claiming nodes needs to respect permissions.

[CMCDragonkai]

For claimNode and claimIdentity, there should be simultaneous handleClaimNode and handleClaimIdentity that is also part of the domain business logic.

This interactions shouldn't be kept in the service layers. The service layers are meant to be thin wrappers.

[CMCDragonkai]

The handleClaimIdentity seems that it shouldn't be in the Provider. But this does require some prototyping to see whether it should be. Whether IdentitiesManager or Provider... etc.

[CMCDragonkai]

Oh I just realised handleClaimIdentity doesn't actually make sense. Because we aren't an "identity".

[tegefaulkes]

How exactly do we tell claims apart?

We have a ClaimLinkNode or ClaimLinkIdentity but they all come out of the sigchain as a Claim. I think the only real difference between them is that the sub parameter would be a NodeidEncoded for a node claim and ProviderIdentityIdEncoded for a identity claim. So it's not impossible to tell them apart but not ideal.

This is not so much a problem for our local sigchain since part of this spec is to have the GestaltGraph updated along side our sigchain.

But for remote nodes we can only get the stream of claims from their sigchain without the context.

Now claims can contain arbitrary information so we can just add a type property to them.

[CMCDragonkai]

There are 2 options:

1. Using the cty as I described here: Replace JOSE with our own tokens domain and specialise tokens for Sigchain, Notifications, Identities and Sessions #481 (comment)
2. Putting typ: 'ClaimLinkIdentity into the payload itself.

The second way is much easier for us to deal with and it disambiguates inside the claim payload... whereas the first way fits the JWT spec better, and it is part of the entire signed claim, not the claim.

They don't conflict, both could be done at the same time. But for now I think the first way is easiest.

Do note that you should be using sigchain.getSignedClaims not getClaims. You need to verify the claims at the discovery level.

The typ property wouldn't conflict with anything listed here: https://www.iana.org/assignments/jwt/jwt.xhtml#claims. So I think we should be good.

[tegefaulkes]

The discovery logic is doing a weird extra level of logic here. When we process a vertex we request the chain data for that vertex. We then iterate over these claims, verify them, add them to the GestaltGraph and then schedule them to be processed.

For some reason we are also requesting the chain data for every node found in these claims and schedule them as well. That should be handled when the original claim is processed. So we're kind of doing this twice here? I don't see a reason for it and it's making the logic here hard to follow in what is already a very long section of code.

I'm just going to remove it.

[CMCDragonkai]

The entire discovery logic can be rewritten. It's significantly legacy now that the GG and Sigchain have been changed.

[CMCDragonkai]

For claimIdentity:

1. This should go into IdentitiesManager, and it will require the ProviderId to identify which provider to the claiming for, and also maybe require the IdentityId in order to identify which identity to do the claiming. The latter requires end to end support for multiple identities per provider.
2. It should then automatically apply changes to the GestaltGraph. Similar to claimNode.

For claimNode:

1. This will end up needing a timeout mechanism for connecting to a node, and also for doing the doubly signed claim between the 2 nodes. The latter is being delayed until the RPC refactoring is done Transport Agnostic RPC #249. In there we are prototyping a better RPC system for peer to peer systems and that should be much easier to having to build an interaction protocol on top of a duplex stream.
2. It needs to automatically apply changes to the GestaltGraph.

For Sigchain:

In the Discovery, it is currently attempting to read all the sigchain claims. We want to avoid this and instead get an "indexed read". There are couple strategies here.

1. We know that the ClaimId is ordered. So in the GG we would know the last ClaimId that we have processed. We can then ask the Sigchain to give us the claims from that last ClaimId and thus we can avoid re-processing already processed claims. This translates to "pagination" parameters for the getSignedClaims and getClaims methods on the Sigchain.
2. This means when we do getSignedClaim we can pass { seek, order } and only process the claims that we need to process. During the discovery process, this does require iterating over the existing set of claims. But this is what we will do normally and keep them in memory because we will be exploring those connections subsequently.

In terms of the TTL for the discovery, that can be done separately later. But the nodes and identities should be re-visited according to a priority and TTL policy. #462

[tegefaulkes]

The refactoring is almost done now. The only build problems left are from the notifications and sessions. I'll have to do something about these before I can do the manual testing. Sessions should be a quick fix but the notifications might be a little trickier since they're using JSON schemas.

I'll see if I can stub out the build problems, otherwise I'll have to refactor it with the token changes.

[CMCDragonkai]

Did you add an additional method to Sigchain.setClaim based on what we discussed? Or was it a different way for node claiming?

[tegefaulkes]

I didn't need to, Both sides were already creating separate claims and singing them for each other. So I replicated that behaviour when refactoring.

[CMCDragonkai]

How does that work? It has be the same claim. Wait... are we saying there are 2 separate claims that each is signing?

So node 1 has made a claim, that is doubly signed.

And node 2 has made a claim, that is doubly signed.

I think I remember that there was some debate about this...

[CMCDragonkai]

So it is actually 2 separate claims because the sigchains are not shared. Things like the claim Id and the previous hash is different and therefore cannot be shared between the 2. So it's like having 2 copies of a contract, and both contracts are doubly signed (but with additional information on each contract that is a bit different).

Therefore we need to ensure some level of commonality between the 2 claims.

The issuer and subject should be the same for both claims. The node that initiates the claiming process is always the issuer. And the responding node is always the subject on both sides of the sigchain.

Furthermore, this means the GestaltLinkNode has to store claims: [ClaimLinkNode, ClaimLinkNode]. Where the order must be the initiating node's claim then the responding node's claim.

This ensures an unambiguous order in the GG, so that when the GG is synchronising, we can easily compare what is different.