@baoshan/octokit_auth-oauth-user-client.js v0.1.0

auth-oauth-user-client.js

Authentication strategy for Octokit without exposing client secret.

Backend service

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 auth-oauth-user-client.js.

Browsers

Load directly from CDNs:

• jsdelivr: https://cdn.jsdelivr.net/gh/octokit/auth-oauth-user-client.js@v0.1.0/dist/index.min.js

<script type="module">
  import { createOAuthUserClientAuth } from "https://cdn.jsdelivr.net/gh/octokit/auth-oauth-user-client.js@v0.1.0/dist/index.min.js";
</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

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/octokit";
  import { createOAuthUserClientAuth } from "https://cdn.jsdelivr.net/gh/octokit/auth-oauth-user-client.js@v0.1.0/dist/index.min.js";

  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://cdn.jsdelivr.net/gh/octokit/auth-oauth-user-client.js@v0.1.0/dist/index.min.js";

  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:

Custom Store

By default, 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

GitHub APP Authentication Object (Expiring Disabled)

GitHub APP Authentication Object (Expiring Enabled)

Development

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

• test: deno test --location=https://acme.com/search?q=octokit --coverage=cov_profile
• show coverage: deno coverage cov_profile
• bundle: deno bundle src/index.ts dist/index.bundle.js
• minify: esbuild dist/index.bundle.js --minify --outfile=dist/index.min.js

Contributing

See CONTRIBUTING.md

License

MIT