cozy/cozy-clearance

Clearance manager for cozy apps

cozy-clearance

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

• server side
• client side

Usage : Server Side

Base Module

documentation

clearance = require 'cozy-clearance'

details  = {email:"[email protected]", contactid:"3615", any:"other field"}
details2 = {email:"[email protected]", 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:"[email protected]", contactid:"3615", any:"other field", key:"secret", perm:"rw"}
#     {email:"[email protected]", 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:"[email protected]", 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:"[email protected]"}, (err) ->
    console.log someModel.clearance
    # [{email:"[email protected]", contactid:"3616", any:"other field", key:"secret2", perm:"rw"}]

# or

clearance.revoke someModel, {any:"other field"}, (err) ->
    console.log someModel.clearance
    # []

Controller :

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
    attachments: optional array of attachments

'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

Usage : Client Side

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) ->
   {doctype, operation, id} = 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 to build the client side.

Use npm run build to build the server side

use npm test to run tests

cozy-clearance's Issues

Might be broken with npm3

This part of the code will break with npm3 :

cozy-clearance/controller.coffee

Lines 29 to 31 in de94b23

	CozyAdapter = try require 'americano-cozy/node_modules/' + \
	'jugglingdb-cozy-adapter'
	catch e then require 'jugglingdb-cozy-adapter'

We can fix it, or we can delete it if all apps now use cozydb.

Suggest to add unknown addresses to contact

When we send a message to an email address that is not in our contacts yet, we should add a way to allow to add it to Contact.

Email is not sent when sharing with someone

(I experience this in cozy-files)

When I add someone to the share list and that I "save" then click "Ok" to send emails, no emails are sent.

It might come from my Cozy, though.

Adding a TTL to clearances

How would you feel about adding a TTL to clearances? The idea would be to share a document for a period of time.

Use cases:

• sharing ephemeral content (hot topic at the moment)
• reducing privacy concerns

When quit the modal (x button or backdrop) with unsaved change, confirmation is asked twice

Allow to add a custom message when sharing an item

See cozy/cozy-files#408

Clearance disclosed in share links

In the share links from Photos and Files,
we have access via the source to all the contacts associated with the current share :
this includes emails, permissions and keys.

It looks like a bad practice.

Requires jade-runtime in app's vendor.js

May be due to jade's version used in cozy-clearance vs brunch's.

Clicking on backdrop doesn't close the modal

It cannot work for two reasons:

• the selector is wrong (see https://github.com/cozy/cozy-clearance/blob/master/client/modal.coffee#L18), it should be .modal-backdrop.fade.in
• the .modal-backdrop is behind the actual modal and its backdrop

The fix for the second reason isn't straightforward: if we put the backdrop in front of the modal, clicks on the modal are going to be captured.

Debug list

Hi,

I met several problems that should be fixed or at least mentioned in the documentation:

• Translations are not there by default
• The modal requires to be extended that way:

class ShareModal extends CozyClearanceModal
    initialize: ->
        super
        @refresh()

• The model should have a .getPublicUrl method (on server side too).
• The model requires two attributes: clearance and type (on server side too).

@model.set 'clearance', []
@model.set 'type', 'album'