Tiny npm package to validate a GitHub API token
MIT License
validate-github-token is a npm package to validate GitHub API OAuth token.
This package can validate the given token
and returns the following information as the result of validation:
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.
npm install --save validate-github-token
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;
}
}
})();
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 willscope: 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
.
token: string
: API token to be validated Required
options: Object
: Objects to configure validation behavior Optional
Promise<Validated>
Returns a promise which is resolved to Validated
interface object. Please read following 'interface Validated'
section for more details.
ValidationError
: Thrown when the given token is actually not authorized or its scopes don't meet options.scope
option valueError
: Thrown when unexpected errors such as network error happeninterface Validated
A TypeScript interface contains the all information returned from API endpoint.
scopes: Array<string>
: An array of scope names added to the API tokenrateLimit: RateLimit
: Rate limit informationinterface 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 countremaining: number
: Remaining rate limit countreset: Date
: The date when the rate limit count is resetDistributed under the MIT license.