Allow to re-use old style SDM and client command and event handlers with function skills

[cdupuis]

This is mostly implemented and QA'ed.

@slimslenderslacks to provide an example on how trigger a auth flow via org-service.

[slimslenderslacks]

Org service url:

https://api.atomist.com
    /v2/auth/teams/{workspace-id}/resource-providers/{resource-provider-id}/token?
        state=guid&
        redirect-uri=https://www.atomist.com/success.html

The stateactually carries a single-use token used to manage a continuation context when used within a bot flow. However, it can still take a user through the ResourceUser linking flow when used outside of a bot flow (the bot command "@atomist authorize github" is really just a link generator).

This url can be clicked in a context where there are already atomist cookies. In that case, we have the Person (auth provider subject and workspace) and we are really just taking them through the ResourceProviderId flow to link that Person to a ResourceUser. If the url is clicked from a browser that is not logged in, it could trigger up to two logins, before being redirected back to the success page.

There are quite a few error cases that the middleware should handle:

• Resource Provider not found. Status 400
• not authorized to collect creds for this resource - this means that the user can auth against the IDP, but is not a member of the workspace. Status 403

If successful, we will redirect to the redirect-uri, and the Person in this workspace will have a linked ResourceUser for this provider.

[slimslenderslacks]

/cc @cdupuis

[slimslenderslacks]

{
    "blocks": [
        {
            "type": "section",
            "text": {
                "type": "mrkdwn",
                "text": "Hi cdupuis :wave:"
            }
        },
        {
            "type": "section",
            "text": {
                "type": "mrkdwn",
                "text": "Great to see you here! You can use Atomsit to link your GitHub identity to your Slack identity.  Atomist GitHub skills executed from Slack will run using your GitHub account.  Examples of GitHub skills that ship with Atomist:"
            }
        },
        {
            "type": "section",
            "text": {
                "type": "mrkdwn",
                "text": "• create Issues \n • generate new Repositories \n • add Slack conversations to Issues"
            }
        },
        {
            "type": "section",
            "text": {
                "type": "mrkdwn",
                "text": "But before you can do all these amazing things, we need you to connect your Slack Identity to your GitHub identity. Simply click the button below:"
            }
        },
        {
            "type": "section",
            "text": {
                "type": "mrkdwn",
                "text": "<https://api.atomist.com/v2/auth/teams/{workspace-id}/resource-providers/{provider-id}/token?state=xxxxxx&redirect-uri=https://www.atomist.com/success.html|link github user>"
            },
            "accessory": {
                "type": "image",
                "image_url": "https://pngimg.com/uploads/github/github_PNG40.png",
                "alt_text": "GitHub"
            }
        }
    ]
}

[slimslenderslacks]

^^ these are the blocks that I'm using right now.

The one important thing missing from this is that the skill will not receive the Auth success or Auth failure event using this url. However, we should add parameters to the url to self-identify the originating skill so that we can route these events back to the skill. This will allow the skill to update the message.

[cdupuis]

How can I pass a request for granted tokens with specific scopes to org-service? This is for cases where there's a token with not enough OAuth scopes.

[slimslenderslacks]

This depends on the resource-provider-id, but for installed GitHub Applications, even the user tokens are still bounded by permissions granted to the Application when it was installed. So for those github user tokens, you will not need to think about scopes. For other resource providers, we will still need to pass through a set of scopes that are being requested.