https://github.com/idiocc/github
The GitHub OAuth Flow For Idio Web Server.
https://github.com/idiocc/github
Last synced: about 1 year ago
JSON representation
The GitHub OAuth Flow For Idio Web Server.
- Host: GitHub
- URL: https://github.com/idiocc/github
- Owner: idiocc
- License: agpl-3.0
- Created: 2019-08-17T20:09:36.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2020-02-27T13:29:47.000Z (over 6 years ago)
- Last Synced: 2025-03-16T18:34:15.698Z (over 1 year ago)
- Language: JavaScript
- Homepage: https://idio.cc
- Size: 140 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# @idio/github
[](https://www.npmjs.com/package/@idio/github)
`@idio/github` is The GitHub OAuth Flow For the [Idio Web Server](https://github.com/idiocc/idio).
```sh
yarn add @idio/github
```
## Table Of Contents
- [Table Of Contents](#table-of-contents)
- [API](#api)
- [`githubOAuth(app, config): void`](#githuboauthapp-_goaapplicationconfig-githuboauthconfig-void)
* [`GithubOAuthConfig`](#type-githuboauthconfig)
* [`GithubEmail`](#type-githubemail)
- [Copyright](#copyright)
## API
The package is available by importing its default function:
```js
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.
- app* _goa.Application: The Goa/Koa Application.
- config* !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 /.
ctx* Context: The app context.
token* string: The exchanged token.
scope* string: The scopes which the user authorised the app to access.
user* !GithubUser: The scopes which the user authorised the app to access.
next* 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.
ctx* !Context: The app context.
error* string: The error type.
description* string: The explanation of the error.
next* function(): Calls next middleware.
```jsx
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(
{ctx.session.user ?
Hello, {ctx.session.user}.{' '}
Sign Out
:
Sign In With GitHub}
(c) Art Deco, 2020
, { 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 https://www.github.com/login/oauth/authorize?client_id=f0a8762e7329780e85de&redirect_uri=http%3A%2F%2Flocalhost%3A5000%2Fgithub%2Fredirect&state=8275&scope=user%3Aemail.',
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.
```js
/**
* @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](https://github.com/idiocc/idio#copyright--license) 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](https://neoluddite.dev) package reward scheme.
