v1.5.2
Kindergarten helps you to separate your business logic into modules and add a security layer over them. It is based on sandbox pattern. Kindergarten will work well with all frameworks and libraries you like: VueJS, React, Angular, Ember, Backbone etc. etc. etc...
Terms Used in Kindergarten
Perimeter
Perimeter is a module that represents an area in you application (certain component, page, button, header etc.). Perimeter defines methods that should be exposed and rules that must be followed on that particular area.
Sandbox
Modules (perimeters) are plugged into sandbox and all exposed methods will be accessible through it. Sandbox is governed by a governess and she is the one who makes sure that all rules are followed in order to prevent any kind of troubles.
Governess
The governess is guarding your sandbox. She makes sure that child doesn't do any unauthorized activities and she can deal with troubles your way!
Child
Child in Kindergarten represents the current user of your application.
Example
;; ;;; // Definition of the perimeterconst homePerimeter = ; // Childconst child = "John Smith Jr."; // Definition of Sandboxconst sandbox = ;sandbox; // No problemosandboxhome; // Throws AccessDenied errorsandboxhome;sandboxhome; // Fails after a whilefor let i = 0; i <= 6; i++ sandboxhome;); sandboxhome; // no problem // Throws AccessDenied errorsandboxhome;
Installation
npm
yarn add kindergarten
Usage
Sandbox
The Sandbox is where the magic happens, that's why Kindergarten makes it really easy for you to create a new sandbox. For instance you can inherit from Sandbox
class:
; { thischild = currentUser // same as this.loadModule(...perimeters) this; } @guard { // this method will be guarded }
You can also use @sandbox
decorator, where inheritance is not applicable:
;;; const adminPerimeter = ; @@ { return this; } { return <Router history=history> <Route path="/" component=App> <IndexRoute component=HomePage /> <Route path="about" component=AboutPage /> <Route path="contact" component=ContactPage /> <Route path="admin" component=AdminPage onEnter=this /> <Route path="login" component=LoginPage /> </Route> </Router> ; }
If you don't want to use decorators, then you can use sandbox
method directly:
// ...;
Rule
Rule
class is used internally be kindergarten. It's probably not a good idea to use it directly, but who knows..
;// or// import { createRule } from 'kindergarten';; ;;; const rule1 = Rule;// or// const rule1 = createRule('can create', [Comment]); const rule2 = Rule; const governess = ;governess; // Head Governess will learn the rules governess; // no problem!governess; // truegoverness; // false
Governess
The guard()
method throws AccessDenied
error by default, but sometimes we want something else. In react-router example above we want to redirect user to login page rather than throwing an error. We could change our guardRoute
method to do that for us, but there is a better way! We can create our own governess for routing!
; { try super; catch e if e instanceof AccessDenied ; ; else ; ; }
and put her on the sandbox our sandbox:
// ...; @ // ...
Kindergarten has also some predefined governesses:
German Governess
German governess loves rules :trollface:. She automatically guards all exposed methods.
; const perimeter = ; // ... const currentUser = role: 'regularGuy' ; const sandbox = ; sandbox; sandboxarticles; // throws AccessDenied error
Strict Governess
Strict governess is useful if you sometimes forget to protect your exposed methods by calling guard()
in their body. Strict governess throws an AccessDenied
error if user calls exposed method that does not call guard()
in it's body. Careful! The exposed method is executed and the AccessDenied
error is thrown afterwards. Rollback is on your own! StrictGoverness
might be useful during development.
; const governess = ; governess
Easy Governess
EasyGoverness
allows child to do anything:
; const perimeter = purpose: 'playing' govern: 'cannot watch' // child can't watch anything return true; expose: 'watch' { this; }; perimetergoverness = EasyGoverness; const sandbox = {};sandbox;sandboxplaying; // easy going
Middleware Governess
MiddlewareGoverness
allows you to execute a given method whenever some exposed method is called through the sandbox.
; const child = {}; const perimeter = ; const sandbox = ; sandbox;sandboxplaying; // callback above will be called
Perimeter
Perimeter contains set of rules for governess and some methods that should be exposed to sandbox.
; const TV = {}; const perimeter1 = ; const perimeter2 = ; const sandbox = ; sandbox; sandboxperimeter1; // truesandboxperimeter2; // falsesandbox; // false
Purpose
When sandbox loads perimeter, a new Purpose
is created. Sandbox copies all exposed methods into the instance of the purpose, so they are callable through the purpose namespace.
; const perimeter = purpose: 'foo' govern: true expose: 'foo' {}; const user = {}; const sandbox = user perimeters: perimeter governess: GermanGoverness; const myPurpose = perimeterpurpose sandbox;myPurpose; myPurpose; // throws Kindergarten.AccessDenied
DO NOT USE Purpose
directly, it's meant to be used internally by a sandbox.
More About Kindergarten
Thanks to..
coffeeaddict for inspiration.
License
The MIT License (MIT) - See file 'LICENSE' in this project
Copyright
Copyright © 2016 Jiri Chara. All Rights Reserved.