@idio/github

@idio/github is The GitHub OAuth Flow For the Idio Web Server.

yarn add @idio/github

API

The package is available by importing its default function:

import github from '@idio/github'

`githubOAuth(`_{app: _goa.Application,
config: !GithubOAuthConfig,}`): void`

The GitHub OAuth Login Routes For The Idio Web Server. Two routes will be configured: one to redirect to GitHub to start authentication, and one to handle the callback from GitHub. They will be installed on the app automatically.

<kbd>app*</kbd> _goa.Application: The Goa/Koa Application.
<kbd>config*</kbd> !GithubOAuthConfig: Options for the middleware.

GithubOAuthConfig: Options for the program.

Name	Type & Description	Default
client_id	string	-

	The app's client id.
client_secret	string	-

	The app's client secret.
path	string	`/auth/github`

	The server path to start the login flaw at.
redirectPath	string	-

	The redirect path (must start with `/`). If not specified, `${path}/redirect` will be used.
scope	string	-

	The scope to ask permissions for. No scope by default.
session	!_goa.Middleware	-

	The configured session middleware in case the `session` property is not globally available on the context.
finish	(ctx: Context, token: string, scope: string, user: !GithubUser, next: function()) => !Promise

	The function to complete the authentication that receives the token and the data about the user, such as name and id. The default function redirects to `/`. <kbd>ctx</kbd> `Context`: The app context. <kbd>token</kbd> `string`: The exchanged token. <kbd>scope</kbd> `string`: The scopes which the user authorised the app to access. <kbd>user</kbd> `!GithubUser`: The scopes which the user authorised the app to access. <kbd>next</kbd> `function()`: Calls next middleware.
error	(ctx: !Context, error: string, description: string, next: function()) => !Promise

	The function to be called in case of error. If not specified, the middleware will throw an internal server error. <kbd>ctx</kbd> `!Context`: The app context. <kbd>error</kbd> `string`: The error type. <kbd>description</kbd> `string`: The explanation of the error. <kbd>next</kbd> `function()`*: Calls next middleware.

import github from '..'
import idio from '@idio/idio'

const Server = async () => {
  const { url, app, router, middleware: {
    session,
  } } = await idio({
    session: {
      keys: [process.env.SESSION_KEY],
    },
  })

  router.get('/', session, (ctx) => {
    ctx.body = render(<html>
      <body>
        {ctx.session.user ?
          <span>Hello, {ctx.session.user}.{' '}
            <a href="/signout">Sign Out</a>
          </span> :
          <a href="/github">Sign In With GitHub</a>}
        <hr/>
        (c) Art Deco, 2020
      </body>
    </html>, { addDoctype: true })
  })
  router.get('/signout', session, (ctx) => {
    ctx.session = null
    ctx.redirect('/')
  })
  app.use(router.routes())

  github(app, {
    session,
    client_id: process.env.CLIENT_ID,
    client_secret: process.env.CLIENT_SECRET,
    scope: 'user:email',
    error(ctx, error) {
      ctx.redirect(`/?error=${error}`)
    },
    path: '/github',
    async finish(ctx, token, scope, user, next) {
      console.log(user.name, user.login, user.company)
      ctx.session.user = user.login
      ctx.session.manuallyCommit()
      ctx.redirect('/')
    },
  })
  return { app, url }
}

[+] CLIENT_ID [+] CLIENT_SECRET [+] SESSION_KEY 
http://localhost:5000 
{
  body: 'Redirecting to <a href="https://www.github.com/login/oauth/authorize?client_id=f0a8762e7329780e85de&amp;redirect_uri=http%3A%2F%2Flocalhost%3A5000%2Fgithub%2Fredirect&amp;state=8275&amp;scope=user%3Aemail">https://www.github.com/login/oauth/authorize?client_id=f0a8762e7329780e85de&amp;redirect_uri=http%3A%2F%2Flocalhost%3A5000%2Fgithub%2Fredirect&amp;state=8275&amp;scope=user%3Aemail</a>.',
  headers: {
    'set-cookie': [
      'koa:sess=eyJnaXRoaWItc3RhdGUiOjgyNzUsIl9leHBpcmUiOjE1ODI4OTY0NTk1OTIsIl9tYXhBZ2UiOjg2NDAwMDAwfQ==; path=/; expires=Fri, 28 Feb 2020 13:27:39 GMT; httponly',
      'koa:sess.sig=mPZuFR0kFz8XFkQRJeuTm3VnMfw; path=/; expires=Fri, 28 Feb 2020 13:27:39 GMT; httponly'
    ],
    location: 'https://www.github.com/login/oauth/authorize?client_id=f0a8762e7329780e85de&redirect_uri=http%3A%2F%2Flocalhost%3A5000%2Fgithub%2Fredirect&state=8275&scope=user%3Aemail',
    'content-type': 'text/html; charset=utf-8',
    'content-length': '391',
    date: 'Thu, 27 Feb 2020 13:27:39 GMT',
    connection: 'close'
  },
  statusCode: 302,
  statusMessage: 'Found'
}

 > Redirect to Dialog https://www.github.com/login/oauth/authorize?client_id=f0a8762e7329780e85de&redirect_uri=http%3A%2F%2Flocalhost%3A5000%2Fgithub%2Fredirect&state=8275&scope=user%3Aemail

If authorisation was successful, the server will make a request to GitHub API at /user path with the token, to get user's public info. This information can then be accessed in the finish function passed in the config.

If the user:email scope was requested, emails returned from the /user/emails API path will also be populated in the emails field. If the user's main email is private, it won't be visible in the email field, so that this scope should be requested if the email address needs to be collected.

GithubEmail

Name	Type & Description
email	string

	The email address.
verified	boolean

	Whether the email was verified.
primary	boolean

	Whether the email is primary.
visibility	string

	Either `public` or `private`.

GithubUser: Public user information

Name	Type & Description
email	?string

	Publicly visible email address. `octocat＠github.com` or `null`.
emails	!Array<!GithubEmail>

	All email addresses accessible if the `user:email` scope was requested.
login	string

	`octocat`
id	number

	1
node_id	string

	`MDQ6VXNlcjE=`
avatar_url	string

	`https://github.com/images/error/octocat_happy.gif`
gravatar_id	string


url	string

	`https://api.github.com/users/octocat`
html_url	string

	`https://github.com/octocat`
followers_url	string

	`https://api.github.com/users/octocat/followers`
following_url	string

	`https://api.github.com/users/octocat/following{/other_user}`
gists_url	string

	`https://api.github.com/users/octocat/gists{/gist_id}`
starred_url	string

	`https://api.github.com/users/octocat/starred{/owner}{/repo}`
subscriptions_url	string

	`https://api.github.com/users/octocat/subscriptions`
organizations_url	string

	`https://api.github.com/users/octocat/orgs`
repos_url	string

	`https://api.github.com/users/octocat/repos`
events_url	string

	`https://api.github.com/users/octocat/events{/privacy}`
received_events_url	string

	`https://api.github.com/users/octocat/received_events`
type	string

	`User`
site_admin	boolean

	false
name	string

	`monalisa octocat`
company	string

	`GitHub`
blog	string

	`https://github.com/blog`
location	string

	`San Francisco`
hireable	boolean

	false
bio	string

	`There once was...`
public_repos	number

	2
public_gists	number

	1
followers	number

	20
following	number

	0
created_at	string

	`2008-01-14T04:33:35Z`
updated_at	string

	`2008-01-14T04:33:35Z`

A custom implementation of the finish function can be provided, only that session must be manually committed after being set.

/**
 * @param {!_idio.Context} ctx
 * @param {string} token
 * @param {string} scope
 * @param {!_idio.GithubUser} user
 */
export const defaultFinish = async (ctx, token, scope, user, next) => {
  ctx.session['token'] = token
  ctx.session['scope'] = scope
  ctx.session['user'] = user
  await ctx.session.manuallyCommit()
  ctx.redirect('/')
}

Copyright

GNU Affero General Public License v3.0

Affero GPL means that you're not allowed to use this middleware on the web unless you release the source code for your application. This is a restrictive license which has the purpose of defending Open Source work and its creators.

Please refer to the Idio license agreement for more info on dual-licensing. You're allowed to use this middleware without disclosing the source code if you sign up on the neoluddite.dev package reward scheme.

	© Art Deco™ for Idio 2020

包详细信息

@idio/github

自述文件

@idio/github

Table Of Contents

API

`githubOAuth(`_{app: _goa.Application,
config: !GithubOAuthConfig,}`): void`

Copyright

更新日志

27 February 2020

1.5.1

1.5.0

23 January 2020

1.4.0

22 January 2020

1.3.0

1.2.0

1.1.0

18 August 2019

1.0.4

1.0.3

1.0.2

1.0.1

1.0.0

17 August 2019

0.0.0

包详细信息

@idio/github

Table Of Contents

API

githubOAuth( app: _goa.Application, config: !GithubOAuthConfig,): void

Copyright

27 February 2020

23 January 2020

22 January 2020

18 August 2019

17 August 2019

0.0.0

`githubOAuth(`_{app: _goa.Application,
config: !GithubOAuthConfig,}`): void`