oauth-app.js

GitHub OAuth toolset for Node.js

Usage

[!IMPORTANT] As we use conditional exports, you will need to adapt your tsconfig.json by setting "moduleResolution": "node16", "module": "node16".

See the TypeScript docs on package.json "exports".
See this helpful guide on transitioning to ESM from @sindresorhus

For OAuth Apps

1import { OAuthApp, createNodeMiddleware } from "@octokit/oauth-app";
2import { createServer } from "node:http";
3
4const app = new OAuthApp({
5  clientType: "oauth-app",
6  clientId: "1234567890abcdef1234",
7  clientSecret: "1234567890abcdef1234567890abcdef12345678",
8});
9
10app.on("token", async ({ token, octokit }) => {
11  const { data } = await octokit.request("GET /user");
12  console.log(`Token retrieved for ${data.login}`);
13});
14
15createServer(createNodeMiddleware(app)).listen(3000);
16// can now receive user authorization callbacks at /api/github/oauth/callback
17// See all endpoints at https://github.com/octokit/oauth-app.js#middlewares

For GitHub Apps

GitHub Apps do not support scopes. If the GitHub App has expiring user tokens enabled, the token used for the octokit instance will be refreshed automatically, and the additional refresh-related properties will be passed to the "token" event handler.

1import { OAuthApp, createNodeMiddleware } from "@octokit/oauth-app";
2import { createServer } from "node:http";
3
4const app = new OAuthApp({
5  clientType: "github-app",
6  clientId: "lv1.1234567890abcdef",
7  clientSecret: "1234567890abcdef1234567890abcdef12345678",
8});
9
10app.on("token", async ({ token, octokit, expiresAt }) => {
11  const { data } = await octokit.request("GET /user");
12  console.log(`Token retrieved for ${data.login}`);
13});
14
15createServer(createNodeMiddleware(app)).listen(3000);
16// can now receive user authorization callbacks at /api/github/oauth/callback
17// See all endpoints at https://github.com/octokit/oauth-app.js#middlewares

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/

OAuthApp.defaults(options)

Create a new OAuthApp with custom defaults for the constructor options

1const MyOAuthApp = OAuthApp.defaults({
2  Octokit: MyOctokit,
3});
4const app = new MyOAuthApp({ clientId, clientSecret });
5// app.octokit is now an instance of MyOctokit

Constructor options

1import { Octokit } from "@octokit/core";
2new OAuthApp({
3  clientId: "1234567890abcdef1234",
4  clientSecret: "1234567890abcdef1234567890abcdef12345678",
5  Octokit: Octokit.defaults({
6    baseUrl: "https://ghe.my-company.com/api/v3",
7  }),
8});

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

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

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

• token.created
• token.reset
• token.refreshed (GitHub Apps only)
• token.scoped (GitHub Apps only)
• token.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.getUserOctokit(options)

1const octokit = await app.getUserOctokit({ code: "code123" });

options are the same as in app.createToken(options)

The octokit instance is authorized using the user access token if the app is an OAuth app and a user-to-server token if the app is a GitHub app. If the token expires it will be refreshed automatically.

app.getWebFlowAuthorizationUrl(options)

Returns and object with all options and a url property which is the authorization URL. See https://github.com/octokit/oauth-methods.js/#getwebflowauthorizationurl

1const { url } = app.getWebFlowAuthorizationUrl({
2  state: "state123",
3  scopes: ["repo"],
4});

app.createToken(options)

The method can be used for both, the OAuth Web Flow and the OAuth Device Flow.

For OAuth Web flow

For the web flow, you have to pass the code from URL redirect described in step 2.

1const { token } = await app.createToken({
2  code: "code123",
3});

Resolves with an user authentication object

For OAuth Device flow

For the device flow, you have to pass a onVerification callback function, which prompts the user to enter the received user code at the received authorization URL.

1const auth = createOAuthUserAuth({
2  clientId: "1234567890abcdef1234",
3  clientSecret: "1234567890abcdef1234567890abcdef12345678",
4  onVerification(verification) {
5    console.log("Open %s", verification.verification_uri);
6    console.log("Enter code: %s", verification.user_code);
7
8    await prompt("press enter when you are ready to continue");
9  },
10});

Resolves with an user authentication object

app.checkToken(options)

1try {
2  const { created_at, app, user } = await app.checkToken({ token });
3  console.log(
4    `token valid, created on %s by %s for %s`,
5    created_at,
6    user.login,
7    app.name,
8  );
9} catch (error) {
10  // token invalid or request error
11}

Resolves with response body from "Check a token" request with an additional authentication property which is a user authentication object.

app.resetToken(options)

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

Resolves with response body from "Reset a token" request with an additional authentication property which is a user authentication object.

app.refreshToken(options)

Expiring tokens are only supported by GitHub Apps, and only if expiring user tokens are enabled.

1const { data, authentication } = await app.refreshToken({
2  refreshToken: "refreshtoken123",
3});

Resolves with response body from "Renewing a user token with a refresh token" request (JSON) with an additional authentication property which is a user authentication object.

app.scopeToken(options)

Scoping a token is only supported by GitHub Apps. "Scoping" in this context means to limit access to a selected installation, with a subset of repositories and permissions.

1const { data, authentication } = await app.scopeToken({
2  clientType: "github-app",
3  clientId: "lv1.1234567890abcdef",
4  clientSecret: "1234567890abcdef12347890abcdef12345678",
5  token: "usertoken123",
6  target: "octokit",
7  repositories: ["oauth-app.js"],
8  permissions: {
9    issues: "write",
10  },
11});

Options

Resolves with response body from "Create a scoped access token" request with an additional authentication property which is a user authentication object.

app.deleteToken(options)

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

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

app.deleteAuthorization(options)

1await app.deleteAuthorization({
2  token: "token123",
3});
4// "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.

Middlewares

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

By default, all middlewares expose the following routes

createNodeMiddleware(app, options)

Native http server middleware for Node.js

1import { OAuthApp, createNodeMiddleware } from "@octokit/oauth-app";
2import { createServer } from "node:http";
3
4const app = new OAuthApp({
5  clientType: "oauth-app",
6  clientId: "1234567890abcdef1234",
7  clientSecret: "1234567890abcdef1234567890abcdef12345678",
8});
9
10const middleware = createNodeMiddleware(app, {
11  pathPrefix: "/api/github/oauth",
12});
13
14createServer(middleware).listen(3000);
15// can now receive user authorization callbacks at /api/github/oauth/callback

createWebWorkerHandler(app, options)

Event handler for web worker environments (Cloudflare workers or Deno).

1// worker.js
2import { OAuthApp, createWebWorkerHandler } from "@octokit/oauth-app";
3const app = new OAuthApp({
4  clientType: "oauth-app",
5  clientId: "1234567890abcdef1234",
6  clientSecret: "1234567890abcdef1234567890abcdef12345678",
7});
8
9const handleRequest = createWebWorkerHandler(app, {
10  pathPrefix: "/api/github/oauth",
11});
12
13addEventListener("fetch", (event) => {
14  event.respondWith(handleRequest(event.request));
15});
16// can now receive user authorization callbacks at /api/github/oauth/callback

createAWSLambdaAPIGatewayV2Handler(app, options)

Event handler for AWS Lambda using API Gateway V2 HTTP integration.

1// worker.js
2import {
3  OAuthApp,
4  createAWSLambdaAPIGatewayV2Handler,
5} from "@octokit/oauth-app";
6const app = new OAuthApp({
7  clientType: "oauth-app",
8  clientId: "1234567890abcdef1234",
9  clientSecret: "1234567890abcdef1234567890abcdef12345678",
10});
11
12export const handler = createAWSLambdaAPIGatewayV2Handler(app, {
13  pathPrefix: "/api/github/oauth",
14});
15
16// can now receive user authorization callbacks at /api/github/oauth/callback

Build Custom Middlewares

When above middlewares do not meet your needs, you can build your own using the exported handleRequest function.

handleRequest function is an abstract HTTP handler which accepts an OctokitRequest and returns an OctokitResponse if the request matches any predefined route.

Different environments (e.g., Node.js, Cloudflare Workers, Deno, etc.) exposes different APIs when processing HTTP requests (e.g., IncomingMessage for Node.js, Request for Cloudflare workers, etc.). Two HTTP-related types (OctokitRequest and OctokitResponse) are generalized to make an abstract HTTP handler possible.

To share the behavior and capability with the existing Node.js middleware (and be compatible with OAuth user authentication strategy in the browser), it is better to implement your HTTP handler/middleware based on handleRequest function.

handleRequest function takes three parameters:

Implementing an HTTP handler/middleware for a certain environment involves three steps:

1. Write a function to parse the HTTP request (e.g., IncomingMessage in Node.js) into an OctokitRequest object. See node/parse-request.ts for reference.
2. Write a function to render an OctokitResponse object (e.g., as ServerResponse in Node.js). See node/send-response.ts for reference.
3. Expose an HTTP handler/middleware in the dialect of the environment which performs three steps:
   1. Parse the HTTP request using (1).
   2. Process the OctokitRequest object using handleRequest.
   3. Render the OctokitResponse object using (2).

Contributing

See CONTRIBUTING.md

License

MIT