npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

octokit-auth-oauth-user-client

v0.1.6

Published

Octokit authentication strategy for OAuth user authentication without exposing client secret.

Downloads

7

Readme

octokit-auth-oauth-user-client.js

Authentication strategy for Octokit without exposing client secret.

Backend Service

octokit-auth-oauth-user-client.js requires a backend service to function. @octokit/oauth-app provides the compatible Node.js/Express.js/Cloudflare Worker/Deno middlewares to interact with octokit-auth-oauth-user-client.js.

NPM

npm install octokit-auth-oauth-user-client

Browsers

Load directly from CDNs:

<script type="module">
  import { createOAuthUserClientAuth } from "https://esm.sh/[email protected]";
</script>

Create An Authenticator Instance

const authenticator = createOAuthUserClientAuth({
  clientId: "client_id", // get client id from https://github.com/settings/apps
  clientType: "github-app", // "github-app" | "oauth-app"
  expirationEnabled: true, // true | false
});

Get Token

Use { type: "getToken" } method to get authentication object from localStorage. Returns null when there is no authentication object found in localStorage.

When both code and state search parameters are present (user being redirected from GitHub login url), "getToken" method will automatically exchange the code search parameter for an authentication object using the backend service.

const auth = await authenticator(); // ≡ ({ type: "getToken" })

Sign In

Use signIn method to clear authentication object from localStorage and redirect user to GitHub login url.

if (!auth) await authenticator({ type: "signIn" });

All Methods

| { type: ? } | Meaning | Note | | :---------------------- | :------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | "getToken" | Get token | See Get token. | | "signIn" | Sign in | See Sign in. | | "createToken" | Exchange code in url parameters for token | Normally the getToken method will exchange code for an access token automatically when both code and state search parameters are present (user being redirected from GitHub login url). | | "checkToken" | Check a token | — | | "createScopedToken" | Create a scoped access token | For OAuth app only. Specify extra parameters like { type: "createScopedToken", target: ... }. | | "resetToken" | Reset a token | — | | "renewToken" | Renewing a user token with a refresh token | The app should enable token expiration in settings (GitHub App only currently) | | "deleteToken" | Delete an app token | Use { type = "deleteToken", offline: true } to delete authentication from localStorage without calling GitHub API via backend service. | | "deleteAuthorization" | Delete an app authorization | |

Usage with Octokit

To use octokit-auth-oauth-user-client with @octokit/core-compatible modules, specify the authentication strategy and authentication strategy options.

<script type="module">
  import { Octokit } from "https://cdn.skypack.dev/octokit";
  import { createOAuthUserClientAuth } from "https://esm.sh/[email protected]";

  const octokit = new Octokit({
    authStrategy: createOAuthUserClientAuth,
    auth: {
      clientId: "client_id", // get client id from https://github.com/settings/apps
      clientType: "github-app", // "github-app" | "oauth-app"
      expirationEnabled: true, // true | false
    },
  });

  const auth = await octokit.auth();
  if (!auth) await octokit.auth({ type: "signIn" });
  else console.log(await octokit.rest.users.getAuthenticated());
</script>

Or

<script type="module">
  import { Octokit } from "https://cdn.skypack.dev/@octokit/core";
  import { createOAuthUserClientAuth } from "https://esm.sh/[email protected]";

  const octokit = new Octokit({
    authStrategy: createOAuthUserClientAuth,
    auth: {
      clientId: "client_id", // get client id from https://github.com/settings/apps
      clientType: "github-app", // "github-app" | "oauth-app"
      expirationEnabled: true, // true | false
    },
  });

  const auth = await octokit.auth();
  if (!auth) await octokit.auth({ type: "signIn" });
  else console.log(await octokit.request("GET /user"));
</script>

createOAuthUserClientAuth(options) or new Octokit({auth})

The createOAuthUserClientAuth method accepts a single options object as argument:

| name | type | description | | :---------------------- | :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | clientId | string | Required. Find Client ID on the app’s about page in settings. | | clientType | string | Required. Either "oauth-app" or "github-app". | | expirationEnabled | boolean | Required. true or false for GitHub App. false for OAuth App. Set according to app settings. | | auth | object | Initial authentication object, defaults to null. See authentication object. | | defaultScopes | string | Only relevant for OAuth App. See available scopes. | | serviceOrigin | string | Defaults to location.origin. Required only when the @octokit/oauth-app Node.js/Express.js/Cloudflare middleware is deployed at a different origin. | | servicePathPrefix | string | Defaults to "/api/github/oauth". Required only when the @octokit/oauth-app Node.js/Express.js/Cloudflare middleware is created with custom pathPrefix. | | authStore | object or false | Custom store to get/set authentication object, false to disable persistence of authentication object. See custom store. | | stateStore | object or false | Custom store to get/set state string, false to disable persistence of state string. | | request | function | You can pass in your own @octokit/request instance. For usage with enterprise, set baseUrl to the API root endpoint. See custom request |

Custom Store

By default, octokit-auth-oauth-user-client.js uses localStorage to store JSON serialized authentication object and state string.

Pass authStore or stateStore in createOAuthUserClientAuth(options) (or new Octokit({auth})) to use your custom code to persist authentication object or state string.

For example:

const authStore = {
  get: async() => {
  // return persisted authentication object when user is signed in;
  // returns `null` when user is signed out
  }
  set: async(auth) => {
    if (auth == null) { /* delete persisted authentication object */ }
    else { /* create or update persisted authentication object */ }
  }
}

const auth = createOAuthUserClientAuth({
  clientId: "client_id",
  authStore
});

Authentication Object

The async auth(options) method returns to an authentication object. There are three possible types of authentication object:

  1. OAuth APP authentication token
  2. GitHub APP user authentication token with expiring disabled
  3. GitHub APP user authentication token with expiring enabled

The differences are

  1. scopes is only present for OAuth Apps
  2. refreshToken, expiresAt, refreshTokenExpiresAt are only present for GitHub Apps, and only if token expiration is enabled

OAuth APP Authentication Object

| name | type | description | | :--------------- | :----------------- | :----------------------------------------- | | type | string | "token" | | tokenType | string | "oauth" | | clientType | string | "oauth-app" | | clientId | string | Client id of the app | | token | string | The user access token | | scopes | array of strings | Array of scope names enabled for the token |

GitHub APP Authentication Object (Expiring Disabled)

| name | type | description | | :--------------- | :------- | :-------------------- | | type | string | "token" | | tokenType | string | "oauth" | | clientType | string | "github-app" | | clientId | string | Client id of the app | | token | string | The user access token |

GitHub APP Authentication Object (Expiring Enabled)

| name | type | description | | :-------------------------- | :------- | :-------------------------------------------------------------- | | type | string | "token" | | tokenType | string | "oauth" | | clientType | string | "github-app" | | clientId | string | Client id of the app | | token | string | The user access token | | refreshToken | string | The refresh token | | expiresAt | string | Date in ISO 8601 format, e.g: 2011-10-05T14:48:00.000Z | | refreshTokenExpiresAt | string | Date in ISO 8601 format, e.g: 2011-10-05T14:48:00.000Z |

Development

Although targeting browsers, this module is written, tested, and bundled using Deno for its simplicity.

  • test: deno task test
  • show coverage: deno task coverage
  • create npm package: deno task build_npm x.x.x
  • bundle using deno: deno bundle mod.ts index.bundle.js

Contributing

See CONTRIBUTING.md

License

MIT