User access control

When you create a server, you can specify an auth(agent, action) method. This method will be called anytime a user tries to do anything, and you can choose whether to accept or reject the attempted action.

The auth method gets access to the user agent, which is a persistent object assigned to each user for the duration of their session.

The auth method is specified in the options object when a server is created and can be for both authentication (is the user who they say they are) and authorization (is the user allowed to perform an action).

Here is an example of that checks the authentication of a user but will not allow them to delete documents

options =
  db:
    type:'memory'
  auth: (agent, action) ->
    if action.type == 'connect'
      # check user has valid authentication token
      if agent.authentication == '1234'
        action.accept()
      else
        action.reject()
    else if action.type == 'delete'
      # no users are allowed to delete
      action.reject()
    else
      # all other actions allowed
      action.accept()

server = connect(...)
sharejs.attach server, options
server.listen 8000

On the client you code might look like this

options = 
  # This could be a string or an object
  authentication: '1234'

sharejs.open 'hello', 'text', options, (error, doc) -> 
  if error
    # handle error
  else 
    # use doc

---

agent object

agent is an object which is uniquely associated with the client connection. The user agent object has the following fields:

• authentication: String or object which is sent when the client connects, use this for authentication tokens.
• headers: Dictionary of the client's HTTP headers. This is set when the client initially connects and is not updated. Header names are lowercase.
• sessionId: A random string associated with the client session.
• connectTime: A Date which says when the session was established
• remoteAddress: The IP or hostname of the client
• name: The user's name or identifier. Defaults to null. You should set this when a client connects.

The user agent object is kept for as long as the corresponding client stays connected. As a result, you can cache your own custom data in the object. For example, you could fetch a user's session cookie in the http headers. Look that up in your session database, then put their actual username in the agent object.

action object

action is an object which represents what the user is trying to do.

The most important fields of the action are action.accept() and action.reject(). Call accept() to allow the user's action and reject() to deny it.

auth must always call either accept or reject exactly one time!

Other fields:

• name: The name of the action.
• type: CRUD action type (create, read, update or delete. ... Or connect.. because I need that too.)
• responded: true when either accept() or reject() has been called, false` until then.

Actions

Name	Type	Other fields	Description
connect	connect	-	A client is trying to connect. All the interesting information is in the user agent object. All clients will generate a connect request, even when their connection is not persistant.
create	create	docName, docType, meta	Create a new document
get snapshot	read	docName	Get a document snapshot
get ops	read	docName, start, end	Get historical operations from start to end on the document. If end is null, the client is requesting all ops.
open	read	docName	The client is opening a document. This will result in a stream of all applied operations. It may be used in conjunction with get ops. (This used to be called 'listen' in ShareJS 0.4)
submit op	update	docName, op, v, meta	Apply op to docName at version v
delete	delete	docName	Permanently delete the named document

Please try it out and file any bugs you find!