User access control

When you create a server, you can specify an auth(client, 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 persistant 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:

options =
  db:
    type:'memory'
  auth: (agent, action) ->
    action.accept()

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

---

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

• 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 client 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!

Other fields:

• name: The name of the action.
• type: CRUD action type (create, read, update or delete. ... Or connect.. because I need that too.)

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!