web-ext-gh-auth v1.0.1

web-ext-gh-auth

Library for simple GitHub authentication in web extensions

This library handles the process of requesting a GitHub personal access token from a user in a web extension.

When the code is run, a new tab is opened asking the user to create a token with the specified list of scopes. As soon as a valid token with all required scopes is provided, the function returns the token together with the authenticated user's login name.

Setup

With NPM and module bundler

1. npm install web-ext-gh-auth
2. Include the authentication page in your extension. If you are using Webpack, you can do so using CopyWebpackPlugin:

// webpack.config.js

const CopyPlugin = require("copy-webpack-plugin");

module.exports = {
  // ...
  plugins: [
    new CopyPlugin([
      {
        from: "./node_modules/web-ext-gh-auth/dist/auth-page/",
        to: "auth-page/",
      },
    ]),
  ],
};

3. Update your extension manifest:

// manifest.json

{
  // ...
  "permissions": ["*://api.github.com/*"]
}

4. Call the promptToken function from a background script to obtain token and username:

// background.js

import { promptToken } from "./path/to/web-ext-gh-auth/background/index";

promptToken(
  "My extension", // Extension name
  ["notifications"], // Required scopes
).then(({ token, username }) => {
  // ...
});

Without NPM

1. Download the package from the releases page and include it in your web extension
2. Update your extension manifest:

// manifest.json

{
  // ...
  "permissions": ["*://api.github.com/*"],
  "background": {
    "scripts": [
      "./path/to/web-ext-gh-auth/background/index.js",
      "./your-background-script.js"
    ]
  }
}

3. Call the promptToken function of the global WebExtGhAuth object from a background script to obtain token and username:

// background.js

WebExtGhAuth.promptToken(
  "My extension", // Extension name
  ["notifications"], // Required scopes
).then(({ token, username }) => {
  // ...
});

Configuration

promptToken(extName, scopes, options);

• extName (required): Name of your web extension (e.g. "My extension")
• scopes (required): Array of scopes the user needs to assign to the GitHub personal access token (e.g. ["notifications", "repo"]). Note: The "user" scope will be added automatically to be able to verify the token and obtain the username
• options: Object with additional optional parameters:
  • authPageDir: Path to the auth-page directory which contains the resources of the token prompt page. Default: "./auth-page"
  • userAgent: User agent to send in the headers of requests to the GitHub API. Default: Name of your extension (extName parameter)

Development

Requirements: Node.js, Yarn, Firefox (the extension can also be loaded manually in Chrome)

1. Clone this repository: git clone REPO_URL
2. Install all dependencies: yarn
3. Generate the library bundle and run the example extension in Firefox: yarn start

Suggestions and contributions are always welcome! Please first discuss changes via issue before submitting a pull request.