GitHub API Token Validation for Node.js

validate-github-token is a npm package to validate GitHub API OAuth token.

This package can validate the given token

• is actually authorized by API endpoint
• has expected API scopes
• doesn't have unexpected API scopes

and returns the following information as the result of validation:

• API scopes which the given token has
• Rate limit

See GitHub official authentication document for more details.

This package aims to make a human-friendly error before actually calling GitHub APIs. It is useful for validating inputs of GitHub Action if you're making a JavaScript Action.

Installation

npm install --save validate-github-token

JavaScript Example

const { validateGitHubToken, ValidationError } = require('validate-github-token');

(async () => {
    try {
        const validated = await validateGitHubToken(
            'your-secret-api-token',
            {
                scope: {
                    // Checks 'public_repo' scope is added to the token
                    included: ['public_repo']
                }
            }
        );

        console.log('Token scopes:', validated.scopes);
        console.log('API rate limit remaining:', validated.rateLimit.remaining);
    } catch(err) {
        if (err instanceof ValidationError) {
            console.error(`Validation failed!: ${err.message}`);
        } else {
            throw err;
        }
    }
})();

API

import { validateGitHubToken, ValidationError } from 'validate-github-token';
// Types for TypeScript
import { ValidateOptions, RateLimit, Validated } from 'validate-github-token';

interface ValidateOptions

A TypeScript interface for configuring the validation behavior. It's keys are as follows:

• userName: string: GitHub user name like "rhysd" for @rhysd. If this value is set, the endpoint will check the token against the user Optional
• scope: Object: Scope validation behavior Optional
  • included: Array<string>: Scope names which should be added to the token Optional
  • excluded: Array<string>: Scope names which should NOT be added to the token Optional
  • exact: Array<string>: Scope names should exactly match to scopes of the token Optional
• agent: https.Agent: Node.js HTTPS agent. For example please pass https-proxy-agent for proxy support Optional
• endpointUrl: string: Custom API endpoint URL. Default value is "https://api.github.com" Optional

e.g.

import {ValidateOptions} from 'validate-github-token';

const opts: ValidateOptions = {
    scope: {
        included: ['public_repo'],
        excluded: ['user'],
    },
    endpointUrl: 'https://github.your.company.com/api/v3',
};

async function validateGitHubToken(token, options?)

A function which validates the given token for the given user. Validation behavior can be configured with the 3rd parameter. It returns the information given from API endpoint. Validation failure is thrown as ValidationError.

Parameters

• token: string: API token to be validated Required
• options: Object: Objects to configure validation behavior Optional

Return value

• Type: Promise<Validated>

Returns a promise which is resolved to Validated interface object. Please read following 'interface Validated' section for more details.

Exceptions

• ValidationError: Thrown when the given token is actually not authorized or its scopes don't meet options.scope option value
• Error: Thrown when unexpected errors such as network error happen

interface Validated

A TypeScript interface contains the all information returned from API endpoint.

• scopes: Array<string>: An array of scope names added to the API token
• rateLimit: RateLimit: Rate limit information

interface RateLimit

A TypeScript interface contains the rate limit information returned from an API endpoint. Please read GitHub's official rate limit documentation for more details.

• limit: number: Max rate limit count
• remaining: number: Remaining rate limit count
• reset: Date: The date when the rate limit count is reset

License

Distributed under the MIT license.