# Migrating

This guide explains the new features and changes to migrate to the Feathers v4 (Crow) release. It expects applications to be using the previous Feathers v3 (Buzzard).

# Versioning

Instead of separate versioning, all modules in the@feathersjs namespace have been updated to use the same version number. This means that the current release (Crow) will beFeathers v4 and using this release means all@feathersjs/ module dependencies show a version of4.x.x (4.0.0-pre.x for prereleases). For historical reasons the first official version will be4.3.0.

Thedatabase adapters will continue to be individually versioned, since they can be used with most Feathers versions from v2 and up.

# Auto upgrade

The@feathersjs/cli comes with a command to automatically upgrade applications generated through@feathersjs/cli (v3.x) with most of the changes necessary for v4. To update the CLI and upgrade your application run:

npm i @feathersjs/cli -gcd myappfeathers upgrade

This will update the dependencies inpackage.json, update thesrc/authentication.js andconfig/default.json with the new authentication setup. The old contents will be kept insrc/authentication.backup.js andconfig/default.backup.json but can be removed once upgrade is completed.

Manual steps are necessary for

• ThehashPassword() hook inservice/users/users.hooks.js which now requires the password field name (usuallyhashPassword('password'))
• Configuring OAuth providers - seeOAuth API
• The authentication Express middleware has been moved toconst { authenticate } = require('@feathersjs/express');
• Any other authentication specific customization - seeauthentication service API
• Feathers client authentication - seeauthentication client API

# Authentication

The@feathersjs/authentication-* modules have been completely rewritten to include more secure defaults, be easier to customize, framework independent and no longer rely on PassportJS. It comes with:

• An extensibleauthentication service that can register strategies and create authentication tokens (JWT by default but pluggable for anything else)
• Protocol independent, fully customizable authentication strategies
• BetterOAuth authentication with 180+ providers supported out of the box without any additional configuration (other than adding the application key and secret)
• Built-in OAuth account linking and cross-domain OAuth redirects

# Manual upgrade

To upgrade manually, replace the existing authentication configuration (usuallysrc/authentication.js orsrc/authentication.ts) with the following:

const{ AuthenticationService, JWTStrategy}=require('@feathersjs/authentication');const{ LocalStrategy}=require('@feathersjs/authentication-local');const{ expressOauth}=require('@feathersjs/authentication-oauth');module.exports=app=>{const authentication=newAuthenticationService(app);  authentication.register('jwt',newJWTStrategy());  authentication.register('local',newLocalStrategy());  app.use('/authentication', authentication);  app.configure(expressOauth());};

import{ Application}from'@feathersjs/feathers';import{ AuthenticationService, JWTStrategy}from'@feathersjs/authentication';import{ LocalStrategy}from'@feathersjs/authentication-local';import{ expressOauth}from'@feathersjs/authentication-oauth';exportdefault(app: Application)=>{const authentication=newAuthenticationService(app);  authentication.register('jwt',newJWTStrategy());  authentication.register('local',newLocalStrategy());  app.use('/authentication', authentication);  app.configure(expressOauth());}

Important: The@feathersjs/authentication-jwt is deprecated since the JWT strategy is now directly included in@feathersjs/authentication.

This will registerlocal,jwt and OAuth authentication strategies using the standard authentication service on the/authentication path. OAuth will only be active if provider information is added to the configuration. The authentication configuration (usually inconfig/default.json) should be updated as follows:

"authentication":{"entity":"user","service":"users","secret":"<your secret>","authStrategies":["jwt","local"],"jwtOptions":{"header":{"typ":"access"},"audience":"https://yourdomain.com","issuer":"feathers","algorithm":"HS256","expiresIn":"1d"},"local":{"usernameField":"email","passwordField":"password"}}

# Authentication client

The v4 authentication client comes with many usability improvements and more reliable socket (re)connection. Since the server side authentication now includes all necessary information, it is no longer necessary to encode the token and get the user separately.

Instead of

const feathersClient=feathers();feathersClient.configure(rest('http://localhost:3030').superagent(superagent)).configure(auth({storage: localStorage}));feathersClient.authenticate({strategy:'local',email:'admin@feathersjs.com',password:'admin'}).then(response=>{  console.log('Authenticated!', response);return feathersClient.passport.verifyJWT(response.accessToken);}).then(payload=>{  console.log('JWT Payload', payload);return feathersClient.service('users').get(payload.userId);}).then(user=>{  feathersClient.set('user', user);  console.log('User', feathersClient.get('user'));}).catch(function(error){  console.error('Error authenticating!', error);});

Can now be done as

const feathersClient=feathers();feathersClient.configure(rest('http://localhost:3030').superagent(superagent)).configure(auth({storage: localStorage}));asyncfunctionauthenticate(){try{const{ user}=await feathersClient.authenticate({strategy:'local',email:'admin@feathersjs.com',password:'admin'});        console.log('User authenticated', user);        console.log('Authentication information is',await app.get('authentication'));}catch(error){// Authentication failed// E.g. show login form}

ThefeathersClient.authenticate() with no parameters to authenticate with an existing token is still avaiable but should be replaced by the more clearfeathersClient.reAuthenticate().

To access the current authentication information, theapp.get('authentication') promise can be used:

// user is the authenticated userconst{ user}=await app.get('authentication');// As a promise instead of async/awaitapp.get('authentication').then(authInfo=>{const{ user}= authInfo;});

# Upgrade Notes

Important things to note:

• Because of extensive changes and security improvements, you should change your JWT secret so that all users will be prompted to log in again.
• Thejwt options have been moved tojwtOptions. It takes alljsonwebtoken options(opens new window). Thesubject optionshould be removed when using the standard setup.
• authStrategies are the strategies that are allowed on the/authentication endpoint
• ThehashPassword hook now explicitly requires the name of the field to hash instead of using a default (change anyhashPassword() to e.g.hashPassword('password')).
• For websockets, theauthenticate event is no longer available. SeeSocket.io Authentication direct usage for more information.

# Feathers core

The following new features and deprecations are included in Feathers v4 core.

# Typescript definitions included

All@feathersjs modules now come with up-to-date TypeScript definitions. Any definitions using@types/feathersjs__*should be removed from your project.

# Services at the root level

Any Feathers application now allows to register a service at the root level with a name of/:

app.use('/', myService);

It will be available viaapp.service('/') through the client and directly athttp://feathers-server.com/ via REST.

# Skip event emitting

Service events can now be skipped by settingcontext.event tonull.

context=>{// Skip sending event  context.event=null;}

#disconnect event

There is now an application leveldisconnect event when a connection gets disconnect:

app.on('disconnect',connection=>{// Do something on disconnect here});

Note: Disconnected connections will be removed from all channels already automatically.

# Deprecated(context, next) and SKIP functionality

In preparation to support Koa style hooks (seefeathersjs/feathers#932(opens new window)) returningSKIP and calling the deprecatednext function in hooks has been removed. ReturningSKIP in hooks was causing issues because

• It is not easily possible to see if a hook makes its following hooks skip. This made hook chains very hard to debug.
• Returning SKIP also causes problems with Feathers internals like the event system

The use-cases forfeathers.SKIP can now be explicitly handled by

• Running hooks conditionally(opens new window) through a flag
• Calling the hook-less service methods of the database adapters
• Settingcontext.event = null to skip event emitting

#@feathersjs/express

• @feathersjs/express/errors has been moved toconst { errorHandler } = require('@feathersjs/express');. It is no longer available via@feathersjs/errors.
• @feathersjs/express/not-found has been moved toconst { notFound } = require('@feathersjs/express');.

# Database adapters

The latest versions of the Feathers database adapters include some important security and usability updates by requiring to explicitly enable certain functionality that was previously available by default.

Important: The latest versions of the database adapters also work with previous versions of Feathers. An upgrade of the@feathersjs/ modules is recommended but not necessary to use the latest database adapter features.

# Querying by id

All database adapters now support additional query parameters forget,remove,update andpatch. If the record does not match that query, even if theid is valid, aNotFound error will be thrown. This is very useful for the common case of e.g. restricting requests to the users company the same way as you already would in afind method:

// Will throw `NotFound` if `companyId` does not match// Even if the `id` is availableapp.service('/messages').get('<message id>',{query:{companyId:'<my company>'}});

# Hook-less service methods

The database adapters now support calling their service methods without any hooks by adding a_ in front of the method name as_find,_get,_create,_patch,_update and_remove. This can be useful if you need the raw data from the service and don't want to trigger any of its hooks.

// Call `get` without running any hooksconst message=await app.service('/messages')._get('<message id>');

Note: These methods are only available internally on the server, not on the client side and only for the Feathers database adapters. They donot send any events.

# Multi updates

Creating, updating or removing multiple records at once has always been part of the Feathers adapter specification but it turned out to be quite easy to miss.

This means applications could be open to queries that a developer did not anticipate (like deleting or creating multiple records at once). Additionally, it could also lead to unexpected data in a hook that require special cases (likecontext.data orcontext.result being an array).

Now, multiplecreate,patch andremove calls (with theid value set tonull) are disabled by default and have to be enabled explicitly by setting themulti option:

const service=require('feathers-<database>');// Allow multi create, patch and removeservice({multi:true});// Only allow create with an arrayservice({multi:['create']});// Only allow multi patch and remove (with `id` set to `null`)service({multi:['patch','remove']});

Important: When enabling multiple remove and patch requests, make sure to restrict the allowed query (e.g. based on the authenticated user id), otherwise it could be possible to delete or patch every record in the database.

# Whitelisting

Some database adapters allowed additional query parameters outside of the official Feathers query syntax. To reduce the risk of allowing malicious queries, only the standard query syntax is now allowed.

Non-standard query parameters (any query property starting with a$) will now throw an error. To allow them, they have to be explicitly whitelisted using thewhitelist option:

const service=require('feathers-<database>');// Allow to use $regex in query parametersservice({whitelist:['$regex']});

Important: Be aware of potential security implications of manually whitelisted options. E.g. Enabling Mongoose$populate can expose fields that are normally protected at the service level (e.g. a users password) and have to be removed separately.

# Backwards compatibility

The REST authentication flow is still the same and the previous socket authentication mechanism is also still supported. New websocket authentication works the same as authentication via REST.

For security reasons, the authentication secret should be changed so that all current JWTs will become invalid and prompt the users to log in again and issue new valid access tokens. The authentication Feathers clients should be updated since it includes many bug fixes on reconnection issues and usability improvements.

# Old client JWT compatibility

Although upgrading the clients and issuing new tokens is highly recommended, the following setup can be used to provide backwards compatible authentication:

const{ AuthenticationService, JWTStrategy}=require('@feathersjs/authentication');const{ LocalStrategy}=require('@feathersjs/authentication-local');const{ expressOauth}=require('@feathersjs/authentication-oauth');classMyAuthenticationServiceextendsAuthenticationService{asyncgetPayload(authResult, params){// Call original `getPayload` firstconst payload=awaitsuper.getPayload(authResult, params);const{ user}= authResult;return{...payload,userId: user.id};}}classLegacyJWTStrategyextendsJWTStrategy{getEntityId(authResult){const{authentication:{ payload}}= authResult;return payload.userId|| payload.sub;}}module.exports=app=>{const authentication=newMyAuthenticationService(app);  authentication.register('jwt',newLegacyJWTStrategy());  authentication.register('local',newLocalStrategy());  app.use('/authentication', authentication);  app.configure(expressOauth());};

# OAuth cookies

To support OAuth for the old authentication client that was using a cookie instead of the redirect to transmit the access token the following middleware can be used:

Note: This is only necessary if the Feathers authentication client is not updated at the same time and if OAuth is being used.

const authService=newAuthenticationService(app);authService.register('jwt',newJWTStrategy());authService.register('local',newLocalStrategy());authService.register('github',newGitHubStrategy());app.use('/authentication', authService);app.get('/oauth/cookie',(req, res)=>{const{ access_token}= req.query;if(access_token){    res.cookie('feathers-jwt', access_token,{httpOnly:false// other cookie options here});}  res.redirect('/redirect-url');});app.configure(expressOauth());

Also updateconfig/default.jsonredirect with/oauth/cookie?:

{"authentication":{"oauth":{"redirect":"/oauth/cookie?"}}}

# PassportJS

PassportJS is the quasi-standard authentication mechanism for Express applications. Unfortunately it doesn't play very well with other frameworks (which Feathers can easily support otherwise) or real time connections. PassportJS can still be used through its direct Express middleware usage and then passing the authentication informationas serviceparams.

← Security