# @jackdbd/oauth2-tokens

[![npm version](https://badge.fury.io/js/@jackdbd%2Foauth2-tokens.svg)](https://badge.fury.io/js/@jackdbd%2Foauth2-tokens)
[![install size](https://packagephobia.com/badge?p=@jackdbd/oauth2-tokens)](https://packagephobia.com/result?p=@jackdbd/oauth2-tokens)
[![CodeCov badge](https://codecov.io/gh/jackdbd/rapido/graph/badge.svg?token=BpFF8tmBYS)](https://app.codecov.io/gh/jackdbd/rapido?flags%5B0%5D=oauth2-tokens)
[![Socket Badge](https://socket.dev/api/badge/npm/package/@jackdbd/oauth2-tokens)](https://socket.dev/npm/package/@jackdbd/oauth2-tokens)

Useful functions when working with OAuth 2.0 tokens.

- [Installation](#installation)
- [Access tokens](#access-tokens)
- [Refresh tokens](#refresh-tokens)
- [Dependencies](#dependencies)
- [References](#references)
- [License](#license)

## Installation

```sh
npm install @jackdbd/oauth2-tokens
```

## Access tokens

The [access tokens](https://datatracker.ietf.org/doc/html/rfc6749#section-1.4) issued by the token endpoint implemented by this plugin are JSON Web Tokens.

Each JWT issued by this token endpoint is **signed** with RS256 using a random [JSON Web Key (JWK)](https://datatracker.ietf.org/doc/html/rfc7517) from a given **private** [JWK Set](https://datatracker.ietf.org/doc/html/rfc7517#section-5).

Each JWT issued by this token endpoint can be **verified** by anyone (for example by a [revocation endpoint](https://www.rfc-editor.org/rfc/rfc7009) or an [introspection endpoint](https://datatracker.ietf.org/doc/html/rfc7662)) using the [the `kid` parameter](https://datatracker.ietf.org/doc/html/rfc7517#section-4.5) from the matching **public** JWK Set.

> [!WARNING]
> Since neither OAuth 2.0 nor IndieAuth require an access token to be implemented as a JSON Web Token, I am considering other implementations. Watch the talk [Rethinking Authentication](https://youtu.be/VhRbvTdX9Ug?si=nvl3HvbzzdTPCght) to learn more about possible alternative implementations for access tokens.

## Refresh tokens

The [refresh tokens](https://indieauth.spec.indieweb.org/#refresh-tokens) issued by the token endpoint implemented by this plugin are [Nano IDs](https://zelark.github.io/nano-id-cc/) generated with [nanoid](https://github.com/ai/nanoid).

> [!TIP]
> Read the article [Why we chose NanoIDs for PlanetScale’s API](https://planetscale.com/blog/why-we-chose-nanoids-for-planetscales-api) for a comparison of Nano ID with UUIDs.

## Dependencies

| Package | Version |
|---|---|
| [@jackdbd/indieauth](https://www.npmjs.com/package/@jackdbd/indieauth) | `0.0.0-canary.1` |
| [@jackdbd/oauth2](https://www.npmjs.com/package/@jackdbd/oauth2) | `0.0.0-canary.1` |
| [@jackdbd/schema-validators](https://www.npmjs.com/package/@jackdbd/schema-validators) | `0.0.0-canary.1` |
| [@sinclair/typebox](https://www.npmjs.com/package/@sinclair/typebox) | `^0.34.14` |
| [ajv](https://www.npmjs.com/package/ajv) | `^8.17.1` |
| [ajv-formats](https://www.npmjs.com/package/ajv-formats) | `^3.0.1` |
| [dayjs](https://www.npmjs.com/package/dayjs) | `^1.11.13` |
| [dayjs-plugin-utc](https://www.npmjs.com/package/dayjs-plugin-utc) | `^0.1.2` |
| [jose](https://www.npmjs.com/package/jose) | `^5.9.6` |
| [ms](https://www.npmjs.com/package/ms) | `3.0.0-canary.1` |
| [nanoid](https://www.npmjs.com/package/nanoid) | `^5.0.9` |

## References

- [Issuing an Access Token - The OAuth 2.0 Authorization Framework (RFC 6749)](https://datatracker.ietf.org/doc/html/rfc6749#section-5)
- [Refreshing an Access Token - The OAuth 2.0 Authorization Framework (RFC 6749)](https://datatracker.ietf.org/doc/html/rfc6749#section-6)
- [Access Token Response - IndieAuth](https://indieauth.spec.indieweb.org/#access-token-response)
- [IndieAuth Rocks! (validator for testing IndieAuth client and server implementations)](https://indieauth.rocks/)
- [IndieAuth scopes](https://indieweb.org/scope#IndieAuth_Scopes): `email`, `profile`
- [Micropub scopes](https://indieweb.org/scope#Microsub_Scopes): `create`, `update`, `delete`, `undelete`, `draft`, `media`

## License

© 2024 - 2025 [Giacomo Debidda](https://www.giacomodebidda.com/) // [MIT License](https://spdx.org/licenses/MIT.html)