@octokit/oauth-app

oauth-app.js

GitHub OAuth toolset for Node.js

Usage

const { OAuthApp, getNodeMiddleware } = require("@octokit/oauth-app");

const app = new OAuthApp({
  clientId: "0123",
  clientSecret: "0123secret",
});

app.on("token", async ({ token, octokit }) => {
  const { data } = await octokit.request("GET /user");
  console.log(`Token retrieved for ${data.login}`);
});

require("http").createServer(getNodeMiddleware(app)).listen(3000);
// can now receive user authorization callbacks at /api/github/oauth/callback

Examples

• Node server with static files served from public/ folder, hosted on Glitch: https://glitch.com/~github-oauth-client
• Serverless functions, hosted on Zeit's now: https://github.com/gr2m/octokit-oauth-app-now-example
• Serverless functions, hosted on AWS (via begin.com): https://github.com/gr2m/octokit-oauth-app-begin-example/

Constructor options

const { Octokit } = require("@octokit/core");
new OAuthApp({
  clientId: 123,
  clientSecret: "secret",
  Octokit: Octokit.defaults({
    baseUrl: "https://ghe.my-company.com/api/v3",
  }),
});

app.on(eventName, eventHandler)

Called whenever a new OAuth access token is created for a user. It accepts two parameters, an event name and a function with one argument

app.on("token.created", async (context) => {
  const { data } = await context.octokit.request("GET /user");
  app.log.info(`New token created for ${data.login}`);
});

The eventName can be one of (or an array of)

• token.created
• token.reset
• token.deleted
• token.before_deleted
• authorization.before_deleted
• authorization.deleted

All event handlers are awaited before continuing.

context can have the following properties

app.octokit

Octokit instance with OAuth App authentication. Uses Octokit constructor option

app.getAuthorizationUrl(options)

Returns a URL string.

const url = app.getAuthorizationUrl({
  state: "state123",
  scopes: ["repo"],
});

app.createToken(options)

const { token, scopes } = await app.createToken({
  state: "state123",
  code: "code123",
});

Resolves with result

app.checkToken(options)

try {
  const { created_at, app, user } = await app.checkToken({ token });
  console.log(
    `token valid, created on %s by %s for %s`,
    created_at,
    user.login,
    app.name
  );
} catch (error) {
  // token invalid or request error
}

Resolves with response body from "Check a token" request.

app.resetToken(options)

const { token } = await app.resetToken({
  token: "token123",
});
// "token123" is no longer valid. Use `token` instead

Resolves with response body from "Reset a token" request.

app.deleteToken(options)

await app.deleteToken({
  token: "token123",
});
// "token123" is no longer valid.

Resolves with response body from "Delete a token" request.

app.deleteAuthorization(options)

await app.deleteAuthorization({
  token: "token123",
});
// "token123" is no longer valid, and no tokens can be created until the app gets re-authorized.

Resolves with response body from "Delete an app authorization" request.

Stateless methods

Each method can be loaded separately to minimize the payload. That is particularly useful for serverless environment, as the payload will be the smallest possible.

const {
  getAuthorizationUrl,
  createToken,
  checkToken,
  resetToken,
  deleteToken,
  deleteAuthorization,
} = require("@octokit/oauth-app");

getAuthorizationUrl(options)

Returns a URL string.

const { getAuthorizationUrl } = require("@octokit/oauth-app");
const url = getAuthorizationUrl({
  clientId: "0123",
  state: "state123",
});

createToken(options)

const { createToken } = require("@octokit/oauth-app");
const { token, scopes } = await createToken({
  clientId: "0123",
  clientSecret: "0123secret",
  state: "state123",
  code: "code123",
});

Resolves with result

checkToken(options)

const { checkToken } = require("@octokit/oauth-app");
try {
  const { created_at, app, user } = await checkToken({
    clientId: "0123",
    clientSecret: "0123secret",
    token: "token123",
  });
  console.log(
    `token valid, created on %s by %s for %s`,
    created_at,
    user.login,
    app.name
  );
} catch (error) {
  // token invalid or request error
}

Resolves with response body from "Check a token" request.

resetToken(options)

const { resetToken } = require("@octokit/oauth-app");
const { token } = await resetToken({
  clientId: "0123",
  clientSecret: "0123secret",
  token: "token123",
});
// "token123" is no longer valid. Use `token` instead

Resolves with response body from "Reset a token" request.

deleteToken(options)

const { deleteToken } = require("@octokit/oauth-app");
await deleteToken({
  clientId: "0123",
  clientSecret: "0123secret",
  token: "token123",
});
// "token123" is no longer valid

Resolves with response body from "Delete a token" request.

deleteAuthorization(options)

const { deleteAuthorization } = require("@octokit/oauth-app");
await deleteAuthorization({
  clientId: "0123",
  clientSecret: "0123secret",
  token: "token123",
});
// "token123" is no longer valid

Resolves with response body from "Delete an app authorization" request.

Middlewares

A middleware is a method or set of methods to handle requests for common environments.

By default, all middlewares expose the following routes

getNodeMiddleware(app, options)

Native http server middleware for Node.js

const { OAuthApp, getNodeMiddleware } = require("@octokit/oauth-app");
const app = new OAuthApp({
  clientId: "0123",
  clientSecret: "0123secret",
});

const middleware = getNodeMiddleware(app, {
  pathPrefix: "/api/github/oauth/",
});

require("http").createServer(middleware).listen(3000);
// can now receive user authorization callbacks at /api/github/oauth/callback

function onUnhandledRequest(request, response) {
  response.writeHead(400, {
    "content-type": "application/json",
  });
  response.end(
    JSON.stringify({
      error: error.message,
    })
  );
}

Contributing

See CONTRIBUTING.md

License

MIT