[code] notify a user about missing scopes on git actions

[akosyakov]

In Theia user gets prompted if there are NOT enough rights to perform git action like push. We should move this logic to the supervisor and expose the notification API from IDE to the supervisor.

[csweichel]

A notification API would be great. How would that API look like?

service NotificationService {
    rpc Notify(NotifyRequest) returns (NotifyResponse) {}

    rpc Subscribe(stream NotifyResponse) returns (stream NotifyRequest) {}
}

message NotifyRequest {
    string title = 1;
    string message = 2;
    // if actions are empty, Notify will return immediately
    repeated string actions = 3;
}

message NotifyResponse {
    // action chosen by the user
    string action = 1;
}

[akosyakov]

something like that but it should be stream right?

[csweichel]

blocked on #3267

[csweichel]

Note: there's no need to make this work in Theia. It's fine if this works in code only.

[csweichel]

Path to scope elevation

1. User does git push
2. Git calls gp credential-helper
3. credential-helper asks supervisor's token service for a token with the repo's host and most scopes
4. supervisor might ask the server for a repo host token - unless it has one cached already
5. credential-helper returns the token to Git
6. Git attempts to perform the operation
7. If the operation fails, Git calls the credential-helper again
8. [scope-guess] credential-helper attempts to guess the scopes required for the original operation
9. credential-helper asks supervisor's token service for a token with the repo's host and the guessed scopes
10. supervisor's token service asks the GitTokenProvider for the scoped token
11. GitTokenProvider checks that all scopes are present, and if not
    • triggers a notification on supervisor's notification service
    • returns no token
12. The notification client shows the notification to the user asking them to visit the "access control page"
13. User elevates scopes on "access control page"
14. User does git push again
15. Git calls gp credential-helper
16. credential-helper asks supervisor's token service for a token with the repo's host and arbitrary scopes
17. supervisor might ask the server for a repo host token
18. credential-helper returns the new token
19. Git operation succeeds

API

For step [scope-guess] we introduce REST "API" on server.
This call is authenticated using Bearer token auth and have a new function scope "gitGuessScopes":

GET /git/guess-scopes
    Parameter: repoURL, operation
Returns either:
    []string of scopes
    user consumable error message why we cannot guess scopes/why scope elevation would not help

[JanKoehnlein]

We decided to start with the new websocket connection from gp to the server instead of adding the REST API described above.

[JanKoehnlein]

Unfortunately, GitHub and Git are not playing together as assumed: The credential helper is only called with erase when user authentication fails (invalid user/password) and not when authorisation fails (insufficient scope). I experimented with a custom credential helper that returns various tokens sniffed from the responses on Gitpod's access control page statically, called by a push to a private repo:

token	credential helper calls	git output
random	get, erase	remote: Invalid username or password. fatal: Authentication failed
default (no public write)	get	remote: Repository not found. fatal: repository not found
public write	get	remote: Repository not found. fatal: repository not found
private read/write	get	success

If we do it as Theia does, the token provider would asynchronously verify the token scopes and fire a notification if they need upgrading. I assume we refrained from that as we'd flood the server with such requests on every request for Git tokens. In the case of Theia that didn't matter so much as the scope validation happened in the client.

@AlexTugarev proposed to fork the credential helper on get and attach to the parent git process, interpret the stderr in the following.

[JanKoehnlein]

We decided to do do similar as in Theia:

1. credential helper returns the token form the supervisor
2. credential helper forks (because it has to exit for git operation to happen) the and does the scope validation/elevation async in parallel.

Functionality-wise it's the same as we do in Theia. Backside is that this might put a bit more load on the server. We can still add some git error detection (like the stderr method above) later on to avoid the validation/elevation step if server load becomes a problem.