From 48da5c1ab1e6296de11f47b80575c14c8b789404 Mon Sep 17 00:00:00 2001
From: John McLear <john@mclear.co.uk>
Date: Wed, 20 May 2015 01:09:35 +0100
Subject: [PATCH] docs for handle message security

---
 doc/api/hooks_server-side.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/doc/api/hooks_server-side.md b/doc/api/hooks_server-side.md
index 717abe75..a4505e93 100644
--- a/doc/api/hooks_server-side.md
+++ b/doc/api/hooks_server-side.md
@@ -214,6 +214,32 @@ function handleMessage ( hook, context, callback ) {
 };
 ```
 
+## handleMessageSecurity
+Called from: src/node/handler/PadMessageHandler.js
+
+Things in context:
+
+1. message - the message being handled
+2. client - the client object from socket.io
+
+This hook will be called once a message arrives. If a plugin calls `callback(true)` the message will be allowed to be processed. This is especially useful if you want read only pad visitors to update pad contents for whatever reason.
+
+**WARNING**: handleMessageSecurity will be called, even if the client is not authorized to send this message. It's up to the plugin to check permissions.
+
+Example:
+
+```
+function handleMessageSecurity ( hook, context, callback ) {
+  if ( context.message.boomerang == 'hipster' ) {
+    // If the message boomer is hipster, allow the request
+    callback(true);
+  }else{
+    callback();
+  }
+};
+```
+
+
 ## clientVars
 Called from: src/node/handler/PadMessageHandler.js