@whook/authorization

A wrapper to provide authorization support to a Whook server

Usage no npm install needed!

<script type="module">
  import whookAuthorization from 'https://cdn.skypack.dev/@whook/authorization';
</script>

README

@whook/authorization

A wrapper to provide authorization support to a Whook server

GitHub license NPM version

This Whook wrapper ties authentication with only two kinds of input:

  • the authorization header which allows several mechanisms to be used including custom ones (this module is using http-auth-utils under the hood). This is the recommended way to authenticate with a server.
  • the access_token defined by the RFC6750 that allows providing the token via query parameters for convenience (mostly for development purpose). Note that you can disable it by setting the DEFAULT_MECHANISM constant to an empty string.

Note that the form-encoded body parameter defined by the bearer authentication RFC is volontarily not supported since nowadays everyone uses JSON and there is no situations where one could not set the token in headers.

To use this wrapper, you'll have to create an authentication service. Here is a simple unique token based implementation (usually in src/services/authentication.ts):

import { autoService } from 'knifecycle';
import YError from 'yerror';
import {
 AuthenticationService,
 BaseAuthenticationData,
} from '@whook/authorization';

export type AuthenticationConfig = {
 TOKEN: string;
};

export type BearerPayload = { hash: string };
export type MyAuthenticationService = AuthenticationService<
 BearerPayload,
 BaseAuthenticationData & {
   userId: number;
 }
>;

export default autoService(initAuthentication);

async function initAuthentication({
 TOKEN,
}: AuthenticationConfig): Promise<MyAuthenticationService> {
 const authentication: MyAuthenticationService = {
   // The authentication service must have a check
   // method which take the type of authentication
   // used by the client and its parsed payload
   check: async (type, data) => {
     if (type === 'bearer') {
       if (data.hash === TOKEN) {
         // When successful, the authentication check
         // must return an object with at least a `scopes`
         // property containing an array of the actual
         // scopes the authentication check resolved to
         return {
           applicationId: 'abbacaca-abba-caca-abba-cacaabbacaca',
           userId: 1,
           scope: 'admin',
         };
       }
       throw new YError('E_BAD_BEARER_TOKEN', type, data.hash);
     }
     // Of course, the service must check the auth type
     // and fail if not supported to avoid security issues
     throw new YError('E_UNEXPECTED_AUTH_TYPE', type);
   },
 };

 return authentication;
}

The properties added next to the scopes one will be passed to the wrapped handlers and an authenticated property will also be added in order for handlers to know if the client were authenticated.

Then, simply add it to your WRAPPERS service (usually in src/services/WRAPPERS.ts):

import { service } from 'knifecycle';
import type { WhookWrapper } from '@whook/whook';
+ import { wrapHandlerWithAuthorization } from '@whook/authorization';

export default service(initWrappers, 'WRAPPERS');

async function initWrappers(): Promise<WhookWrapper<any, any>[]> {
-   const WRAPPERS = [];
+   const WRAPPERS = [wrapHandlerWithAuthorization];

  return WRAPPERS;
}

Then add the config and the errors descriptors or provide your own (usually in src/config/common/config.js):

import { DEFAULT_ERRORS_DESCRIPTORS } from '@whook/http-router';
+ import {
+   AUTHORIZATION_ERRORS_DESCRIPTORS,
+   WhookAuthorizationConfig
+ } from '@whook/authorization';

// ...

export type AppConfigs = WhookConfigs &
+  WhookAuthorizationConfig &
  APIConfig;

const CONFIG: AppConfigs = {
  // ...
-   ERRORS_DESCRIPTORS: DEFAULT_ERRORS_DESCRIPTORS,
+   ERRORS_DESCRIPTORS: {
+     ...DEFAULT_ERRORS_DESCRIPTORS,
+     ...AUTHORIZATION_ERRORS_DESCRIPTORS,
+   },
  // ...
};

export default CONFIG;

To see a complete usage of this wrapper, you may have a look at the @whook/example project.

API

wrapHandlerWithAuthorization(initHandler) ⇒ function

Wrap an handler initializer to check client's authorizations.

Kind: global function
Returns: function - The handler initializer wrapped

Param Type Description
initHandler function The handler initializer

Authors

License

MIT