# @geztio/checkpoint-server

> A module to provide an easy but configurable way to implement token based authentication for a node server

Latest version **0.9.7** (published 2023-10-27) · Unlicensed license · 0 weekly downloads

## Install

```sh
npm install @geztio/checkpoint-server
pnpm add @geztio/checkpoint-server
yarn add @geztio/checkpoint-server
bun add @geztio/checkpoint-server
```

## 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.9.7 |
| Published | 2023-10-27 |
| First published | 2023-10-25 |
| Weekly downloads | 0 |
| License | Unlicensed |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 6 |
| Unpacked size | 51 KB |
| Known vulnerabilities | 0 (+4 in 2 direct dependencies) |
| Install scripts | no |
| Maintainers | geztio-jacob |

## Links

- npm: https://www.npmjs.com/package/@geztio/checkpoint-server
- npm.io page: https://npm.io/package/@geztio/checkpoint-server

## Dependencies (6)

- [passport](https://npm.io/package/passport.md) 0.4.0
- [jsonwebtoken](https://npm.io/package/jsonwebtoken.md) 8.5.1
- [passport-jwt](https://npm.io/package/passport-jwt.md) 4.0.0
- [passport-http](https://npm.io/package/passport-http.md) 0.3.0
- [passport-facebook](https://npm.io/package/passport-facebook.md) 3.0.0
- [passport-google-oauth](https://npm.io/package/passport-google-oauth.md) 2.0.0

## Recent versions

- 0.9.7 (latest) — 2023-10-27
- 0.8.1 — 2023-10-25

## README

# checkpoint

A module to provide an easy but configurable way to implement token based authentication for a node server

# Install

This is a Node.js module available through the internal Conqr npm registry.

Before installing, download and install Node.js. Node.js 0.10 or higher is required.

Installation is done using the npm install command:

```bash
$ npm install @conqr/{module name}
```

# Usage

### new Authenticator(options)

Creates a new auhtenticator.

`options`:

* `basicAuthHandler`: handler for basic http authentication in the form of `(req, userid, password, done) => void`.
  > `req` is the request being authenticated. `userid` and `password` are extracted from the http basic auth header. `done(err, user)` is a callback that determines whether the authentication was successful based on the arguments sent. If `err` is not null, or `user` is false, the request is unauthorized. 
* `tokenAuthHandler`: handler for token authentication in the form of `(req, token, payload, header, signature, done) => void`.
  > `token` is the jwt token extracted by the `tokenExtract` hook. `payload`, `header`, and `signature` are the different parts of the verified jwt token.
* `tokenExtract`: a function to extract a token from a request in the form of `(request) => token`. The function receives a request object and should return the extracted token, or `null` if no token could be extracted.
  > A number of predefined extraction methods are provided by the `ExtractJwt` class provided in this module. Ex. `ExtractJwt.fromAuthHeaderAsBearerToken()`
* `tokenPayload`: hook for building the payload to be encoded into a jwt token, `(user) => payload`. The function receives a user object which can be used to put user specific claims into the `payload`.
* `tokenStore`: hook executed after the token has been generated but not yet passed to the final request handler. `token` is the encoded jwt token, and `payload` now contains all claims both user specific and global, that have been encoded into the jwt token.
* `jwt`: (see [jsonwebtoken](https://github.com/auth0/node-jsonwebtoken/#jwtsignpayload-secretorprivatekey-options-callback))
  * `secretOrKey`: a string, buffer, or object containing either the secret for HMAC algorithms or the PEM
encoded private key for RSA and ECDSA. In case of a private key with passphrase an object `{ key, passphrase }` can be used (based on [crypto documentation](https://nodejs.org/api/crypto.html#crypto_sign_sign_private_key_output_format)), in this case be sure you pass the `algorithm` option.
  * `jwtIdProvider`: function to generate unique ids for tokens.
  * `options`
    * `algorithm` (default: `HS256`)
    * `expiresIn`: expressed in seconds or a string describing a time span [zeit/ms](https://github.com/zeit/ms). (default: `1h`)
      > Eg: `60`, `"2 days"`, `"10h"`, `"7d"`. A numeric value is interpreted as a seconds count. If you use a string be sure you provide the time units (days, hours, etc), otherwise milliseconds unit is used by default (`"120"` is equal to `"120ms"`).
    * `notBefore`: expressed in seconds or a string describing a time span [zeit/ms](https://github.com/zeit/ms). 
      > Eg: `60`, `"2 days"`, `"10h"`, `"7d"`. A numeric value is interpreted as a seconds count. If you use a string be sure you provide the time units (days, hours, etc), otherwise milliseconds unit is used by default (`"120"` is equal to `"120ms"`).
    * `audience` (default: `conqr-client`)
    * `issuer` (default: `conqr-server`)
    * `noTimestamp`
    * `header`
    * `ignoreExpiration`: if `true` do not validate the expiration of tokens.
    * `ignorNotBefore`: if `true` do not validate the notBefore of tokens.
    * `clockTolerance`: number of seconds to tolerate when checking the `nbf` and `exp` claims, to deal with small clock differences among different servers
    * `maxAge`: the maximum allowed age for tokens to still be valid. It is expressed in seconds or a string describing a time span [zeit/ms](https://github.com/zeit/ms). 
      > Eg: `1000`, `"2 days"`, `"10h"`, `"7d"`. A numeric value is interpreted as a seconds count. If you use a string be sure you provide the time units (days, hours, etc), otherwise milliseconds unit is used by default (`"120"` is equal to `"120ms"`).
* `generateEndpoints`: option to automatically generate protected token generation endpoints for each auth method. (default: `true`)
  > Generated endpoints are in the form `/auth/<method>`. Ex. `/auth/basic`, `/auth/google`, etc.
* `OAuthCallbackHost`: the base url for OAuth callbacks. Only used in conjunction with `generateEndpoints`.
  > When this option is set, the `callbackURL` property of the OAuth provider options is ignored. Callback endpoints for OAuth providers will be generated in the following pattern: `<host>/auth/<provider>/callback`. Ex. `https://example.com/auth/google/callback`.

* `OAuthProviders`: object where every key is an OAuth provider, currently supported providers are `google` and `facebook`. 
  > At the moment all supported providers have the same options:
  * `google`
    * `handler`: handler for authentication with this provider: `(request, accessToken, refreshToken, profile, done) => void`. Called after the OAuth provider authentication is completed.
      > `accessToken` is the token provided by the OAuth provider for access to the providers API, `refreshToken` is used to renew the OAuth access token, `profile` contains the userdata provided by the OAuth provider.
    * `options`
      * `clientID`
      * `clientSecret`
      * `callbackURL`: if `OAuthCallbackHost` is set this will be ignored.
        > If set, this property should be a complete url. ex. `https://example.com/google/callback`
      * `failureRedirect`: a redirect path that will be used if the OAuth handler signals an unsuccessful authntication.



### Authenticator.initExpress(router);

Initializes the authenticator for use with Express.js

`router`: express app or router for which authentication should be handled. If `generateEndpoints` is set, this is the router on which they will be added.
  > The initialize function has to be run before any middleware is used.

### Authenticator.authenticateWithToken()

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