# token-introspection

> Library to introspect tokens of services following RFC-7662

Latest version **3.3.0** (published 2024-05-15) · MIT license · 0 weekly downloads

## Install

```sh
npm install token-introspection
pnpm add token-introspection
yarn add token-introspection
bun add token-introspection
```

## Health

**Score 23/100 (F)** — status: abandoned.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.3.0 |
| Published | 2024-05-15 |
| First published | 2017-02-20 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/token-introspection) |
| Module format | CommonJS |
| Node | >=10 |
| Dependencies | 5 |
| Unpacked size | 13 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 13 |
| Author | Joakim Wånggren |
| Maintainers | rodbiffi, mike-dvtka, spp-owner, filipgolonka, schibstedbot, joawan, gustavkj, pakerstrand, userpixel, zamzterz |
| Keywords | token, introspection, rfc7662 |

## Links

- npm: https://www.npmjs.com/package/token-introspection
- Repository: https://github.com/schibsted/node-token-introspection
- Homepage: https://github.com/schibsted/node-token-introspection#readme
- Issues: https://github.com/schibsted/node-token-introspection/issues
- npm.io page: https://npm.io/package/token-introspection

## Dependencies (5)

- [debug](https://npm.io/package/debug.md) ^4.3.4
- [pem-jwk](https://npm.io/package/pem-jwk.md) ^2.0.0
- [jwks-rsa](https://npm.io/package/jwks-rsa.md) ^3.0.0
- [jsonwebtoken](https://npm.io/package/jsonwebtoken.md) ^9.0.0
- [form-urlencoded](https://npm.io/package/form-urlencoded.md) ^6.1.0

## Recent versions

- 3.3.0 (latest) — 2024-05-15
- 3.2.0 — 2023-01-10
- 3.1.1 — 2023-01-10
- 3.1.0 — 2022-03-15
- 3.0.3 — 2021-09-07
- 3.0.2 — 2021-04-20
- 3.0.1 — 2021-04-14
- 3.0.0 — 2021-03-30
- 2.1.0 — 2020-03-25
- 2.0.1 — 2020-01-09
- 2.0.0 — 2019-10-15
- 1.2.0 — 2019-06-26
- 1.1.0 — 2018-06-12
- 1.0.0 — 2018-05-15
- 0.8.0 — 2018-05-15
- … 11 more at https://npm.io/package/token-introspection/versions

## README

# node-token-introspection

Node token introspection package introspects a token towards an oauth service that follows the [RFC 7662](https://tools.ietf.org/html/rfc7662).

## Install

```bash
npm install token-introspection --save
```

# Node version

Currently we only support latest Node LTS.
If you want to use an earlier version of node, please use
[babel register](https://babeljs.io/docs/usage/babel-register/).

## Usage

Introspect package is configured with endpoint and client credentials, and a function is returned.
Calling that function with token, and optional token_type_hint will return a
[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).

```javascript
const tokenIntrospection = require('token-introspection')({
    endpoint: 'https://example.com/introspect',
    client_id: '<Client ID>',
    client_secret: '<Client Secret>',
});

tokenIntrospection(token).then(console.log).catch(console.warn);
```

## Configuration

| Field                     | Required | Comment |
| ------------------------- | :------: | ------- |
| jwks                      | (X)      | Static JWKS of trusted keys, for example `{keys: [{kty:'RSA',n:'4-4mhUVhY2k',e:'AQAB'}]}` |
| jwks_uri                  | (X)      | URL of a trusted JWKS, for example `https://example.com/jwks` |
| endpoint                  | (X)      | URL to call, for instance https://example.com/introspect |
| allowed_algs              |          | List of allowed signing algorithms, defaults to `['RS256']` |
| jwks_cache_enabled        |          | If jwks response should be cached, defaults to true |
| jwks_cache_maxentries     |          | How many jwk's to cache, defaults to 10 |
| jwks_cache_time           |          | How long a jwk is cached, in ms, defaults to 5 min |
| jwks_timeout              |          | Timeout in ms for fetching jwks, defaults to 10s |
| jwks_ratelimit_enabled    |          | If ratelimit of calls to jwks endpoint, defaults to true |
| jwks_ratelimit_per_minute |          | Limits of jwks calls, defaults to 60 rpm |
| jwks_client_fetcher       |          | Fetcher function that is used by the [Jwks Client library](https://www.npmjs.com/package/jwks-rsa). It must resolve to the Jwks response. Some `jwks_*` options do not apply when using the custom jwks client fetcher |
| client_id                 |          | Client ID used to introspect |
| client_secret             |          | Client secret used to introspect |
| access_token              |          | Access token used to introspect, instead of client credentials |
| user_agent                |          | Defaults to `token-introspection` |
| fetch                     |          | Defaults to [node-fetch](https://github.com/bitinn/node-fetch), but you can inject [zipkin-instrumentation-fetch](https://www.npmjs.com/package/zipkin-instrumentation-fetch). |

At least one of the required configuration parameters `jwks`, `jwks_uri` or `endpoint` must be specified.

### Flexibility in fetch
As you can provide your own `fetch` implementation, it is possible override the agent `fetch` uses for various purposes.
These purpose can be things like zipkin/tracing, self signed certificates, client TLS authentication, proxy, adding a keepAlive, etc.

```js
const HttpsProxy = require('https-proxy-agent');
const proxy = new HttpsProxy(proxySettings);

const customFetch = (endpoint, options) => {
    options.agent = proxy;
    process.env.HTTPS_PROXY = proxy;
    return fetch(endpoint, options);
};

const tokenIntrospection = require('token-introspection');
const introspector = tokenIntrospection({endpoint, ..., fetch: customFetch});
```

## Errors
This is a promise/async library, and will resolve with success or reject with an Error subclass.

* `IntrospectionError`: Base error, thrown when introspection fails for some reason.
* `ConfigurationError`: Thrown when configuration is wrong.
* `MalformedTokenError`: Thrown when token is malformed, currently not publicly exposed.
* `TokenNotActiveError`: Thrown when token is not active, base error for `TokenExpiredError` and `NotBeforeError`.
* `TokenExpiredError`: Thrown in local introspection when token has expired.
* `NotBeforeError`: Thrown in local introspection when token is not yet valid

## Showing debug output

Set the environment variable `DEBUG=token-introspection`.

---
_Source: https://npm.io/package/token-introspection · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._