cozy-clearance

cozy-clearance provides clearance management

cozy-clearance

Helper package to manage clearances in cozy. This package include two parts:

  • server side
  • client side

documentation

clearance = require 'cozy-clearance'
 
details  = {email:"steve@exemple.com"contactid:"3615"any:"other field"}
details2 = {email:"jane@exemple.com"contactid:"3616"any:"other field"}

The clearance.add function allows you to add a rule to a model

clearance.add someModel'rw'details(err) ->
    clearance.add someModel'r'details2(err) ->
        console.log someModel.clearance
# [ 
#     {email:"steve@exemple.com", contactid:"3615", any:"other field", key:"secret", perm:"rw"} 
#     {email:"jane@exemple.com", contactid:"3616", any:"other field", key:"secret2", perm:"rw"} 
# ] 

The clearance.check function allows you to check a request against the model. It looks for the key in the request's querystring The callback is called with the matching rule if found, false otherwise

req.query.key = "secret"
clearance.check someModel'r'req(err, rule) ->
    # rule == {email:"steve@exemple.com", contactid:"3615", any:"other field", key:"secret", perm:"rw"} 
 
clearance.check someModel'w'req(err, rule) ->
    # rule == false, steve doesn't have the 'w' permission 

The clearance.revoke function allows you to revoke a rule for the model. All rules matching the given object will be revoked

clearance.revoke someModel{email:"steve@exemple.com"}(err) ->
    console.log someModel.clearance
    # [{email:"jane@exemple.com", contactid:"3616", any:"other field", key:"secret2", perm:"rw"}] 
 
# or 
 
clearance.revoke someModel{any:"other field"}(err) ->
    console.log someModel.clearance
    # [] 

To use the client side of cozy-clearance, you will need to expose some of the controller's routes.

# in routes.coffee 
clearance = require 'cozy-clearance'
 
# use mailSubject & mailTemplate functions to customize the sent mail. 
clearanceCtl = clearance.controller
    mailSubject: (options) -> # options.doc , options.url 
    mailTemplate: (options) -> # options.doc , options.url 
 
'docid':
    param: # fetch and save in req.doc 
'clearance/contacts':
    get: clearanceCtl.contactList
'clearance/contacts/:contactid':
    get: clearanceCtl.contact
'clearance/contacts/:contactid.jpg':
    get: sharing.contactPicture
'clearance/:docid'
    put: clearanceCtl.change
'clearance/:docid/send':
    post: clearanceCtl.sendAll
 

Your client side environement should include the following :

  • a global require & require.define, following the commonjs convention (like brunch)
  • a global t function that handles translations

Include the file client-build.js or client-build.min.js in your vendor/scripts folder and use it like this :

CozyClearanceModal = require 'cozy-clearance/modal_share_view'
new CozyClearanceModal model: someModel

You can override some methods :

class YourModalView extends CozyClearanceModal
 
    # change the permissions method to add possible permissions 
    permissions: ->
        'r': 'see this'
        'rw': 'see and edit'
        'rwy': 'see, edit and do Y'
        'rwz': 'see, edit and do Z'
        # note : list all possible combinations, here, you can't have both Y & Z permissions 
 

See cozy-files for heavy customization.

The contactCollection can be plugged to your app's realtime :

contactCollection = require 'cozy-clearance/contact_collection'
socketListener.process = (event) ->
   {doctypeoperationid} = event
   # ... 
   contactCollection.handleRealtimeContactEvent event
 
## Locales 
 
The client-side library use the following locale keys:
 - "cancel"
 - "confirm"
 - "copy paste link"
 - "mail not send"
 - "modal error"
 - "modal ok"
 - "modal question " + type + " shareable"
 - "modal send mails
 - "modal shared " + type + " custom msg"
 - "modal shared public link msg"
 - "modal shared with people msg"
 - "no forgot"
 - "no"
 - "only you can see"
 - "perm"
 - "private"
 - "r"
 - "revoke"
 - "save"
 - "see link"
 - "send email hint"
 - "send mails question"
 - "server error occured"
 - "share confirm save"
 - "share forgot add"
 - "shared"
 - "sharing"
 - "yes forgot"
 - "yes"
 
## Contribute
 
Use [coffeegulp](https://github.com/minibikini/coffeegulp) to build the client
side.
 
Use npm run build to build the server side
 
use npm test to run tests