search

MatrixAI / Polykey-Docs

Documentation for Polykey
https://polykey.com/docs/
GNU General Public License v3.0
2 stars 5 forks source link

Wiki Reference Articles for Session Management and Node Protocols, Gestalt Protocols, Identity Protocols #4

Open CMCDragonkai opened 3 years ago

CMCDragonkai commented 3 years ago

Session management and node protocols include:

These wiki articles should go into Reference under js-polykey. As these are library references for how the system works. They are not usecases nor are they theory.

Keep them high level so they don't go out of date. However we should refer to the relevant exceptions expected.

Interacting side effects, and things to be ware of when programming with essential to document.

Use asciiflow to prototype the diagrams first, then use plantuml to finish off, in particular the sequence diagrams. Component diagrams are a more freeform, so they can stay as asciiflow diagrams.

Refer to the network reference article as an example: https://github.com/MatrixAI/js-polykey/wiki/network

Target wiki article is located here: https://github.com/MatrixAI/js-polykey/wiki/Session-Management

Tasks

  1. [ ] - Build component diagrams for all subsystems
  2. [ ] - Build sequence diagrams to illustrate the protocol
  3. [ ] - Introduce user as a lifeline in the sequence diagram to represent what the user does with respect to the Client. Such as providing the password when the user prompts.
  4. [ ] - Introduce concurrent effects in the sequence diagram, especially when multiple calls are updating the session token. To do this, add an additional life-line representing a second Client when it tries to call simultaneously and results in conflict when updating the session token (and thus resolving the update by making usage of lock). The lock itself can be represented as another lifeline.
  5. [ ] - Explain how our session tokens are not OTP tokens but are similar to access-tokens in OAuth2 protocol that uses short lifetimes. It has a similar effect to OTP tokens.
CMCDragonkai commented 3 years ago

3 additional things missing in the wiki reference for sessions:

  1. Introduce user as a lifeline in the sequence diagram to represent what the user does with respect to the Client. Such as providing the password when the user prompts.
  2. Introduce concurrent effects in the sequence diagram, especially when multiple calls are updating the session token. To do this, add an additional life-line representing a second Client when it tries to call simultaneously and results in conflict when updating the session token (and thus resolving the update by making usage of lock). The lock itself can be represented as another lifeline.
  3. Explain how our session tokens are not OTP tokens but are similar to access-tokens in OAuth2 protocol that uses short lifetimes. It has a similar effect to OTP tokens.

Sequence diagrams should be able to make use of plantuml as these concepts should be well-established in uml formality.

CMCDragonkai commented 3 years ago

The 3 diagrams that are useful across alot of domains:

CMCDragonkai commented 3 years ago

Gitlab natively supports plantuml, but our wiki will need this provided via plantuml.com and embedded as an image see: https://blog.anoff.io/2018-07-31-diagrams-with-plantuml/. Use this: http://www.plantuml.com/plantuml/uml/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000

The plantuml should be saved in the wiki as well though to prevent us from losing the diagram code.

CMCDragonkai commented 2 years ago

@emmacasolin since you are getting sessions stuff working. Your diagrams and documentation work there would satisfy this issue.

CMCDragonkai commented 2 years ago

You might want to clarify this too:

Explain how our session tokens are not OTP tokens but are similar to access-tokens in OAuth2 protocol that uses short lifetimes. It has a similar effect to OTP tokens.

CMCDragonkai commented 2 years ago

But this issue also requires moving/copying some content regarding gestalts and identity claims into reference oriented docs too.

CMCDragonkai commented 2 years ago

Gestalt discovery reference should take some ideas/diagrams from: https://gitlab.com/MatrixAI/Engineering/Polykey/js-polykey/-/merge_requests/195#note_597545555

This may be related to the decentralized trust, although this can be a separate document.

CMCDragonkai commented 2 years ago

Interaction of ACL requires reference documentation as well, it's always been a bit complicated:

People always forget how it works.

emmacasolin commented 2 years ago

I've renamed the sessions wiki to "Service Authentication" (https://github.com/MatrixAI/js-polykey/wiki/Service-Authentication) to match the sidebar and updated the information there to include session interception, session token management, the CARL, and the new exceptions. Also created some puml diagrams which I've uploaded to the js-polykey wiki repo and embedded into the wiki page following these instructions: https://blog.anoff.io/2018-07-31-diagrams-with-plantuml/

CMCDragonkai commented 2 years ago

Actually rename the service auth to session management. It's a better name anyway.

On 24 November 2021 4:16:05 pm AEDT, emmacasolin @.***> wrote:

I've renamed the sessions wiki to "Service Authentication" (https://github.com/MatrixAI/js-polykey/wiki/Service-Authentication) to match the sidebar and updated the information there to include session interception, session token management, the CARL, and the new exceptions. Also created some puml diagrams which I've uploaded to the js-polykey wiki repo and embedded into the wiki page following these instructions: https://blog.anoff.io/2018-07-31-diagrams-with-plantuml/

-- You are receiving this because you were assigned. Reply to this email directly or view it on GitHub: https://github.com/MatrixAI/js-polykey/issues/239#issuecomment-977540633 -- Sent from my Android device with K-9 Mail. Please excuse my brevity.

emmacasolin commented 2 years ago

Renamed to "Session Management" and updated sidebar to match https://github.com/MatrixAI/js-polykey/wiki/Session-Management

CMCDragonkai commented 2 years ago

@joshuakarp can you review the session management wiki?

@emmacasolin a quick glance, looks really nice. However I think it's missing an architectural diagram that can be derived from:

Both of these architectural diagrams should be brought together and integrated into your documentation. These will be essential to understanding where logic is located, not just the flow of execution as you currently have with your sequence diagrams.

CMCDragonkai commented 2 years ago

Recommend copying the ASCII diagram verbatim, and then adapt the second diagram into ASCII too.

CMCDragonkai commented 2 years ago

Also are you also diagramming the flow of acquiring parameters too? In terms of PK_PASSWORD and PK_TOKEN for determining unattended or attended?

CMCDragonkai commented 2 years ago

Also please document the 3 modes of authentication. Details are on the MR comments. I bolded it and we discussed before.

CMCDragonkai commented 2 years ago

3 modes discussed here: https://gitlab.com/MatrixAI/Engineering/Polykey/js-polykey/-/merge_requests/213#note_730292155

Please indicate this by how the tlsConfig is set and how that affects it. Document which modes we are using and why.

joshuakarp commented 2 years ago

Some comments on the session management wiki article:

CMCDragonkai commented 2 years ago

To be clear, session management and CARL is about "authentication" not "authorization".

emmacasolin commented 2 years ago

I think it's missing an architectural diagram that can be derived from:

Draft combined diagram here. I tried to keep as much of both diagrams as I could without making it too confusing, but would appreciate feedback on how clear it is.

``` @startuml !theme plain hide empty description title Session Management state "A Unary Call" as UC ##green { state "Call Option" as CO ##lightskyblue { state "Call Credential" as CC ##lightskyblue { } } } state "GRPC Agent" as GA ##green state "SessionManager" as SM ##lightskyblue state "Unary Response" as UR ##green { state "Metadata" as M ##lightskyblue : Session Token } state "GRPC Client" as GC ##green state "GRPC Client" as GC2 ##green state "GRPC Client" as GC3 ##green state "Session" as S ##lightskyblue state "Session" as S2 ##lightskyblue state "Session" as S3 ##lightskyblue state "User/CLI" as U ##orange state "User/CLI" as U2 ##orange state "GRPC Client" as GC4 ##green state "Session" as S4 ##lightskyblue state "\~/.polykey/client/token" as T ##lightskyblue state "\~/.polykey/client/token" as T2 ##lightskyblue CC : 1. empty CC : 2. basic token CC : 3. bearer token GC -l[#green]-> UC UC -d[#green]-> GA GA -r[#green]-> UR UR -r[#green]-> GC GA -u[#lightskyblue]-> SM : generates token SM -d[#lightskyblue]-> GA : new token GC -[#lightskyblue]-> S : writeToken S -[#lightskyblue]-> GC : readToken GC -[#orange]-> U : prompt pass U -[#orange]-> GC : password S -[#lightskyblue]-> T : writeToken T -[#lightskyblue]-> S : readToken GC2 -u[#green]-> GA GC3 -u[#green]-> GA GC4 -u[#green]-> GA GA -d[#green]-> GC2 GA -d[#green]-> GC3 GA -d[#green]-> GC4 GC2 -d[#lightskyblue]-> S2 S2 -u[#lightskyblue]-> GC2 GC3 -d[#lightskyblue]-> S3 S3 -u[#lightskyblue]-> GC3 GC4 -d[#lightskyblue]-> S4 S4 -u[#lightskyblue]-> GC4 GC2 -[#orange]-> U2 U2 -[#orange]-> GC2 GC3 -[#orange]-> U2 U2 -[#orange]-> GC3 GC4 -[#orange]-> U2 U2 -[#orange]-> GC4 S2 -d[#lightskyblue]-> T2 T2 -u[#lightskyblue]-> S2 S3 -d[#lightskyblue]-> T2 T2 -u[#lightskyblue]-> S3 S4 -d[#lightskyblue]-> T2 T2 -u[#lightskyblue]-> S4 GC2 -r[hidden]-> GC3 GC3 -r[hidden]-> GC4 S2 -r[hidden]-> S3 S3 -r[hidden]-> S4 UC -d[hidden]-> UR note bottom of UR #lightskyblue Session token may not exist (if call fails). end note note right of UC #lightskyblue We use a Call Credential "Generator" by default which reads the token from the session and attaches it as a bearer token. If the password is supplied it overrides this as a basic token. A valid call must include either a basic or bearer token. end note note bottom of T #lightskyblue When the GRPC Client receives a response with a Session Token in Metadata it needs to save the new token for subsequent GRPC calls. end note note left of SM #lightskyblue A new Session Token is generated on every GRPC call. This is done automatically by the GRPC Agent. end note note bottom of T2 #orange Clients on the same host share a Session Token. Concurrency is managed via file locking. end note note left of GC2 #orange There can be multiple clients on the same host/user, each one handling its own call. end note note left of GA #green The GRPC Agent accepts authenticated requests (calls) from a number of clients. It will return a response to the client, and if the request is valid the response will contain the requested data along with a new Session Token in its metadata. end note @enduml ```
CMCDragonkai commented 2 years ago

Might want to incorporate the https://excalidraw.com/#room=57543403694c95eba2e9,5qJFVQlpWc0vegUgEAQIpA diagram too.

flow

CMCDragonkai commented 2 years ago

And this:

                                       ┌────────────────┐
                                       │ SessionManager │  SessionManager generates and verifies session tokens
Client on different host/user          └────────┬───────┘
                                                │
    ┌───────────────┐                   ┌───────┴──────┐
    │ PolykeyClient ├───────────────────► PolykeyAgent │   Agent accepts authenticated requests
    └───────┬───────┘                   └───────▲──────┘
            │                                   │
       ┌────┴────┐            ┌─────────────────┼─────────────────┐
       │ Session │            │                 │                 │
       └─────────┘    ┌───────┴───────┐ ┌───────┴───────┐ ┌───────┴───────┐
                      │ PolykeyClient │ │ PolykeyClient │ │ PolykeyClient │  Multiple CLI & GUI clients on same host/user
                      └───────┬───────┘ └───────┬───────┘ └───────┬───────┘
                              │                 │                 │
                         ┌────┴────┐       ┌────┴────┐       ┌────┴────┐
                         │ Session │       │ Session │       │ Session │     Session manages token lifecycle
                         └────┬────┘       └────┬────┘       └────┬────┘
                              │                 │                 │
                              └─────────────────┼─────────────────┘
                                                │
                                   ┌────────────┴────────────┐
                                   │ ~/.polykey/client/token │  Concurrency managed via file lock
                                   └─────────────────────────┘

                         Shared session token for authenticated requests

For component diagram wise.

CMCDragonkai commented 2 years ago

Draft combined diagram here. I tried to keep as much of both diagrams as I could without making it too confusing, but would appreciate feedback on how clear it is.

You should change GRPC Agent to GRPC Server to avoid confusion between our client and agent "servers".

CMCDragonkai commented 2 years ago

Discovery is complex and is worth diagramming. Also consider sequence diagrams for its edge conditions: https://github.com/MatrixAI/js-polykey/pull/311#issuecomment-1049484685