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

[CMCDragonkai]

Session management and node protocols include:

• Authentication system and token usage between Client GRPC and PK Agent
• Identity Claim (Augmentation) Process
• Node Claims Process

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]

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]

The 3 diagrams that are useful across alot of domains:

• Component Diagrams - these are so freeform it may be better to leave them as ASCIIflow diagrams, especially if a specific layout is required
• Sequence Diagrams - good to use plantuml for
• State Transition Diagrams - these are quite tricky so it's good to use plantuml for these

[CMCDragonkai]

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]

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

[CMCDragonkai]

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]

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

[CMCDragonkai]

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]

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

• Integrate gestalt graph with ACL Polykey#184
• ACL integration into the CLI Polykey#207 (comment)
• https://gitlab.com/MatrixAI/Engineering/Polykey/js-polykey/-/merge_requests/188#note_601518284
• https://gitlab.com/MatrixAI/Engineering/Polykey/js-polykey/-/merge_requests/199

People always forget how it works.

[emmacasolin]

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]

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]

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

[CMCDragonkai]

@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:

• Ensure Session token remains safe with multiple processes. Polykey#236 (comment)
• https://gitlab.com/MatrixAI/Engineering/Polykey/js-polykey/-/merge_requests/213#note_728972375

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]

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

[CMCDragonkai]

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]

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

[CMCDragonkai]

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]

Some comments on the session management wiki article:

• I feel this would benefit from a quick paragraph or so about specifically what our session token is doing for Polykey (most likely at the very beginning, before "Starting a Session"). We kind of just start talking about it without giving motivation for it
• There's some discrepancies between spelling of "authorisation"/"authorization" - I believe @CMCDragonkai is preferring US English, so these should all be changed to "authorization"
• "Session Interception" section was really clear - diagram was great, and it's made me understand this process more as well
• "Session Management" diagram: I'm not sure that the 2 final returning blue dotted lines should be there (the "returns requested data B" and "displays requested data B"). Hasn't the call failed, so some kind of error is returned instead?
• "Retrying a CLI Call": I think some of the "programming-speak" should be using code markdown style (e.g. ErrorClientAuthMissing, and perhaps even PK_PASSWORD)
• "This metadata is encoded using the first set value from the following in order:" the wording confused me here a bit. I initially thought this was referring to an actual set. Maybe something like "This metadata is encoded using the first defined value discovered from the following sources (in order of precedence):"

[CMCDragonkai]

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

[emmacasolin]

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

• Ensure Session token remains safe with multiple processes. Polykey#236 (comment)
• https://gitlab.com/MatrixAI/Engineering/Polykey/js-polykey/-/merge_requests/213#note_728972375

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]

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

[CMCDragonkai]

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]

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]

Discovery is complex and is worth diagramming. Also consider sequence diagrams for its edge conditions: MatrixAI/Polykey#311 (comment)