Create DESIGN.md

[expede]

Preview 📜

The Single Source of Truth:tm: for the Fission Server technical design, terms, concepts, and APIs.

Related

• Closes Write design document for the Fission Server #151

[expede]

Flipping to RFR, but I expect that there will be questions or things that need more clarity. Have at it!

[hugomrdias]

The a server account should support multiple Identifier DIDs (Root DIDs) ie. if a user doesnt want to trust google sync he may need to add multiple passkey identifiers to the same account.

Or we need to rely on device linking only.

[expede]

The a server account should support multiple Identifier DIDs (Root DIDs)

@hugomrdias How are you thinking about that? We can pass a list to the create function, but all of those need to be alterted to the existence of those UCANs later. There's a section in here for what is essentially a UCAN outbox, but the other devices need to know to pull. If they're online we could do this via AWAKE pubsub, but that's not the general case.

Starting with linking and ucan:* is probably the fastest way to get up and running, and we do the "multiple parents" version later.

Thoughts?

[hugomrdias]

@hugomrdias How are you thinking about that? We can pass a list to the create function, but all of those need to be alterted to the existence of those UCANs later.

im just thinking in a PUT /v0/api/account/identifier that adds an new identifier that is used to validate further GET v0/api/account

There's a section in here for what is essentially a UCAN outbox, but the other devices need to know to pull. If they're online we could do this via AWAKE pubsub, but that's not the general case.

didnt get this part

Starting with linking and ucan:* is probably the fastest way to get up and running, and we do the "multiple parents" version later.

yes!

[expede]

im just thinking in a PUT /v0/api/account/identifier that adds an new identifier that is used to validate further GET v0/api/account

Sorry, I'm still not sure that I follow 😅 You mean an endpoint where people can register their DIDs with the server? How does that enable GET /v0/api/account requests?

didnt get this part

Ah, sorry. Basically if we more closely follow a capabilities model than we have historically — previously we let users tell us a DID rather than giving the agent generate it's own unique DID — we can later do things like give the agnet multiple parents or directly delegate to multiple users. That either requires that they be online, or we need to put them somewhere that they can find them later. An outbox is one such mechanism: "periodically check here for more UCANs". This store could even be unauthenticated — UCANs are technically secure in public — but getting an invication to that endpoint can act as a gossip-capable store-and-forward outbox for them to pull from and see if they have any UCANs waiting for them.

[codecov]

Codecov Report

Merging #162 (695aa47) into main (3c4a962) will increase coverage by 3.03%.
Report is 17 commits behind head on main.
The diff coverage is 36.58%.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #162      +/-   ##
==========================================
+ Coverage   20.44%   23.47%   +3.03%     
==========================================
  Files          54       56       +2     
  Lines        2040     2147     +107     
  Branches     1267     1334      +67     
==========================================
+ Hits          417      504      +87     
+ Misses       1075      974     -101     
- Partials      548      669     +121     

Files	Coverage Δ
fission-server/src/routes/doh.rs	19.23% <ø> (ø)
fission-server/src/routes/health.rs	51.85% <ø> (ø)
fission-server/src/router.rs	18.18% <0.00%> (-0.57%)	⬇️
fission-server/src/models/volume.rs	29.62% <16.66%> (+22.22%)	⬆️
fission-server/src/error.rs	44.44% <40.00%> (ø)
fission-server/src/middleware/logging.rs	24.08% <41.66%> (+5.56%)	⬆️
fission-server/src/extract/authority.rs	30.23% <52.63%> (+10.23%)	⬆️
fission-server/src/test_utils/mod.rs	41.00% <50.00%> (+2.72%)	⬆️
fission-server/src/models/account.rs	46.29% <56.00%> (+10.58%)	⬆️
fission-server/src/authority.rs	24.32% <26.66%> (+10.03%)	⬆️
... and 1 more

... and 15 files with indirect coverage changes

[hugomrdias]

Sorry, I'm still not sure that I follow 😅 You mean an endpoint where people can register their DIDs with the server? How does that enable GET /v0/api/account requests?

User 1 registers Account 1 with Identifier 1 and now can invoke account caps, after User 1 wants to associate another Identifier 2 to Account 1 so he can invoke account caps with Identifier 2 also.

Does this make it clearer ?

we can later do things like give the agnet multiple parents or directly delegate to multiple users.

Give agents multiple parents? What do you mean, im my view agent are ephemeral and don't matter much in terms of delegation audience. That why we target Identifiers and not agents.

[matheus23]

@hugomrdias IIUC, (and my hope is this helps clarify this), it's decent UX to allow associating multiple passkeys with a single account, correct? So, each passkey would be an 'Identifier', and supporting adding multiple is so that the UX is better for passkeys, right?

[matheus23]

Let's get this into main so it's discoverable.

We'll PR some elaboration on the REST routes later.

[matheus23]

Please don't mind if I do! 👀

[expede]

Thanks for merging after our call @matheus23 👍

[expede]

That why we target Identifiers and not agents.

We may be using these terms differently. I tend to use "agent" to mean anything with a DID, by analogy to actors (but tehse don't fit the exact definition of an actor). I don't use the term Identifier because it's so broad.

User 1 registers Account 1 with Identifier 1 and now can invoke account caps, after User 1 wants to associate another Identifier 2 to Account 1 so he can invoke account caps with Identifier 2 also.

Gotcha. I think we agree on the goal. This topic came up on a call with Philipp earlier, and we can still achieve what you're describing with the design I'm proposing. Since the delegation goes through the server, we can add and remove delegations at will without any additional mechanisms.