validate-github-token

GitHub API Token Validation for Node.js
=======================================
[![CI workflow][ci-badge]][ci]
[![npm package][npm-badge]][npm]

[validate-github-token][repo] is a [npm package][npm] to validate [GitHub API][dev-gh] 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][gh-auth] 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][gh-action] if you're making a [JavaScript Action][js-action].

Installation

``
npm install --save validate-github-token
`

JavaScript Example

`javascript
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

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

$3

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

- userName: string: GitHub user name like "rhysd" for [@rhysd][me]. If this value is set, the endpoint will
check the token against the user Optional
- scope: Object: Scope validation behavior Optional
- included: Array: Scope names which should be added to the token Optional
- excluded: Array: Scope names which should NOT be added to the token Optional
- exact: Array: 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][proxy] for proxy support Optional
- endpointUrl: string: Custom API endpoint URL. Default value is "https://api.github.com" Optional

e.g.

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

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

$3

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

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

$3

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

- scopes: Array: An array of scope names added to the API token
- rateLimit: RateLimit: Rate limit information

$3

A TypeScript interface contains the rate limit information returned from an API endpoint.
Please read [GitHub's official rate limit documentation][rate-limit] 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.

[repo]: https://github.com/rhysd/validate-github-token
[npm]: https://www.npmjs.com/package/validate-github-token
[dev-gh]: https://developer.github.com/
[proxy]: https://www.npmjs.com/package/https-proxy-agent
[rate-limit]: https://developer.github.com/v3/rate_limit/
[me]: https://github.com/rhysd
[gh-auth]: https://developer.github.com/v3/#authentication
[ci-badge]: https://github.com/rhysd/validate-github-token/workflows/CI/badge.svg?branch=master&event=push
[ci]: https://github.com/rhysd/validate-github-token/actions?query=workflow%3ACI+branch%3Amaster
[npm-badge]: https://badge.fury.io/js/validate-github-token.svg
[gh-action]: https://github.com/features/actions
[js-action]: https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-a-javascript-action