A stix module that allows you to setup enrichers, validators and infinitely more for actions.
Gates are like middleware, but different. They allow you to grant or reject passage. They sit between your router and your action, securing your endpoints. Here's a simplified overview of the flow:
Request--->Router+--->Gates+------>Dispatcher+
| | |
v v v
404 4xx 2xx
| | |
+---------+-----------------+-->Response
- The request will pass through the gates in the order you defined them.
- A gate is allowed to return
undefined
,boolean
or astix.Response
instance. - If a gate denies access to the request, the request goes straight to the response phase.
If you initialized a new stix project using the boards cli stix preset, stix-gates will already be included in your project and you can move on to the using section. If not, keep reading.
- In your stix project, simply run
yarn add stix-gates
. - Add the module to your project's
src/config/modules.ts
:
import { ModuleManagerConfigInterface } from 'stix';
import { Gates } from 'stix-gates';
export const modules: ModuleManagerConfigInterface = [
Gates,
// Your other modules.
];
Setting up stix-gates is easy.
- Make sure you have a
gates.ts
atsrc/config/gates.ts
. - Add it to your config (add
export * from './gates';
to yoursrc/config/index.ts
)
Done. The stix-gates module will do the rest... Except for writing your gates of course, for which I do encourage you to keep reading!
Using gates is, in the spirit of stix as magic-less as possible. This means that you maintain a clear overview of what's going on, and you can cmd+click/ctrl+click (I don't judge... Publicly.) your way through your codebase as happy as the day you were born.
Let's take a look at the src/config/gates.ts
file.
import { Gate } from 'stix-gates';
import { SomeController } from '../api/controllers';
import { IsAuthenticated, IsNotGuest } from '../api/gates';
const compose = Gate.compose;
export const gate = {
locations: [ path.resolve(__dirname, '..', 'src', 'Gate') ],
gates: {}, // Optional service-manager config
rules: new Map([
// By default, allow no access to anything.
// This is also the stix-gates default when no gates were found.
['*', false],
// Allow access to all actions, except one.
// Produces: { OpenController: { '*': true, secretAction: false } }
[ OpenController, { '*': true, secretAction: false } ],
// Compose some rules for the UserController using the helper.
// Produces: { UserController: { profile: [ isAuthenticated, isNotGuest ] } }
compose(UserController, { profile: [ isNotGuest ] }, [ isAuthenticated ]),
]),
};
As you can see, you can use the reference to your controller, and similarly to your gates. Strings also work, so using Gate.compose()
is optional.
Now that you know how to configure gates, you'll need to start writing them.
You can put your gates anywhere you like. They can even be imported from other modules, how convenient is that? Here are a couple of examples to help you understand how gates work.
Simple result
import { ContextInterface } from 'stix';
export class IsAuthenticated extends AbstractGate {
public async passThrough (ctx: ContextInterface) {
return !!ctx.state.user;
}
}
- Gates can be async functions.
ctx
is the koa context. It holds the request, response, body etc.- When a gate returns
false
, stix-gates will create aClientErrorResponse.forbidden()
response for you. - When it returns
true
, the next gate will be applied. If this was the last gate, the action will be dispatched.
Default value
import { ContextInterface } from 'stix';
export class IsAuthenticated extends AbstractGate {
public passThrough (ctx: ContextInterface) {
if (!ctx.state.user) {
return false;
}
}
}
- Gates are not required to return a value.
- When nothing was returned (or
undefined
) the gate passes automatically (defaulting totrue
). - This allows you to use gates to patch the
ctx
with additional data. One example is using a gate to fetch a user from the database based on the user_id provided in the JWT.
Custom response
import { ContextInterface } from 'stix';
import { AbstractGate } from 'stix-gates';
export class IsAuthenticated extends AbstractGate {
public passThrough (ctx: ContextInterface) {
if (!ctx.state.user) {
return this.unauthorizedResponse();
}
}
}
- Returning
false
from a gate defaults to aClientErrorResponse.forbidden()
denying the request. - Returning any other
Response
type will also result in the request being terminated with your custom response. - This allows you to decide what type of response gets sent back early if needed.
- Common responses are available on your gate when extending AbstractGate.
More available response methods
The AbstractGate extends the AbstractResponseHelper, giving you the following helper methods:
- okResponse
- createdResponse
- notFoundResponse
- requestTimeoutResponse
- forbiddenResponse
- badRequestResponse
- unauthorizedResponse
- internalServerErrorResponse
- permanentRedirectResponse
You can read more about resonses in the Stix documentation.
stix-gates comes with a couple of helpers to make working with it even more fun.
Because gates are indexed using Maps, and not everyone is comfortable with an array of arrays, we added the Gate.compose()
helper method. The added advantage is that it allows you to define some baseRules, and it'll merge those in for every action defined.
Code speaks. This example uses the baseRules
:
compose(UserController, { profile: [ isNotGuest ] }, [ isAuthenticated ]);
// Produces:
[
UserController,
{
profile: [ isAuthenticated, isNotGuest ],
},
]
And here's a simple example using booleans:
// Allow access to all actions, except one.
compose(OpenController, { '*': true, secretAction: false });
// Produces:
[
OpenController,
{
'*': true,
secretAction: false,
}
]
This is especially useful if your rules repeat often.
MIT.