# easy-jwt

> Simple boilerplate implementation for JWT authorisation

Latest version **0.2.2** (published 2023-02-07) · ISC license · 0 weekly downloads

## Install

```sh
npm install easy-jwt
pnpm add easy-jwt
yarn add easy-jwt
bun add easy-jwt
```

## Health

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

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

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.2.2 |
| Published | 2023-02-07 |
| First published | 2023-02-05 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 48.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | _gav |

## Links

- npm: https://www.npmjs.com/package/easy-jwt
- Repository: https://github.com/Gallmond/easy-jwt
- Homepage: https://github.com/Gallmond/easy-jwt#readme
- Issues: https://github.com/Gallmond/easy-jwt/issues
- npm.io page: https://npm.io/package/easy-jwt

## Dependencies (1)

- [jsonwebtoken](https://npm.io/package/jsonwebtoken.md) ^9.0.0

## Recent versions

- 0.2.2 (latest) — 2023-02-07
- 0.2.1 — 2023-02-07
- 0.1.4 — 2023-02-06
- 0.1.3 — 2023-02-05
- 0.1.2 — 2023-02-05
- 0.1.1 — 2023-02-05

## README

# easy-jwt

A dead easy implementation of JWT as authentication.

## Simple usage

```js
// initialise EasyJWT with some definitions
const easyAuth = new EasyJWT({
  secret: 'my-application-secret'
  accessToken: { expiresIn: 60 * 60 * 24 },     // expires in a day
  refreshToken: { expiresIn: 60 * 60 * 24 * 7 } // expires in a week
})

// create token for a user
const {accessToken, expiresIn, refreshToken} = easyAuth.createTokens(
  currentUser.id,                       // this is the 'subject' of our JWT
  { employeeLevels: ['administrator'] } // these are any arbitrary custom claims
)

// this token can then later be verified like
const tokenPayload = await easyAuth.verifyJwt( accessToken )
tokenPayload.employeeLevel // ['administrator']

// or refreshed like so
const newAccessToken = easyAuth.refreshJwt( refreshToken )

// the custom claims are automatically copied across
newAccessToken.employeeLevel // ['administrator']
```

## Advanced usage

We can add additional validation steps like so. 

The custom function should return true if the token *is* valid

```js
// any access tokens should have claim employeeLevel array containing 'administrator'
easyAuth.accessTokenValidation((jwt, payload) => {
  return payload.employeeLevel.includes('administrator')
})

// refresh tokens should *not* be revoked
easyAuth.refreshTokenValidation((jwt, payload) => {
  return RevokedTokensTable.where('token', '=', jwt).count() < 1
})
```

If we tell EasyJWT what the subject refers to, we can even use the tokens directly
to return your models

```ts
type ReturnsUser = Promise<User | undefined>

easyAuth.getsModel<ReturnsUser>(async (jwt, payload) => {
  return await UserTable.where('id', '=', payload.sub ).first() ?? undefined
})

const authorisedUser = await easyAuth.getModel<ReturnsUser>( accessToken )
```

## Errors

Custom errors that may be thrown include:

### EasyJWTValidationError
When custom validation checks fail

### EasyJWTTypeError
When a refresh attempt is made on a token of type other than `refresh_token`

### EasyJWTSubjectError
When a token is missing a subject

### EasyJWTGetModelError
When at attempt is made to use `getModel` before the retrieval function has been defined

### All base `jsonwebtoken` errors

see project [readme](https://github.com/auth0/node-jsonwebtoken#errors--codes)

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