Merge branch 'master' into tres

Conflicts:
	include/Contact.php
	include/ItemObject.php
	include/api.php
	include/attach.php
	include/diaspora.php
	include/dir_fns.php
	include/enotify.php
	include/event.php
	include/expire.php
	include/items.php
	include/notifier.php
	include/notify.php
	include/photos.php
	include/taxonomy.php
	include/text.php
	include/widgets.php
	include/zot.php
	mod/admin.php
	mod/channel.php
	mod/dirsearch.php
	mod/display.php
	mod/editwebpage.php
	mod/events.php
	mod/home.php
	mod/item.php
	mod/manage.php
	mod/mood.php
	mod/network.php
	mod/page.php
	mod/photos.php
	mod/ping.php
	mod/post.php
	mod/thing.php
	mod/viewsrc.php
	view/css/mod_events.css

1 files changed, 288 insertions, 269 deletions

diff --git a/mod/post.php b/mod/post.php
index 14cdfd9be..fe0860cc6 100644
--- a/mod/post.php
+++ b/mod/post.php
@@ -1,20 +1,21 @@
-<?php /** @file */
+<?php
 
 /**
- * Zot endpoint
+ * @file mod/post.php
+ *
+ * @brief Zot endpoint.
+ *
  */
 
-
 require_once('include/zot.php');
 
-
-function post_init(&$a) {
-
-	// Most access to this endpoint is via the post method.
-	// Here we will pick out the magic auth params which arrive
-	// as a get request, and the only communications to arrive this way.
-
 /**
+ * @brief HTTP POST entry point for Zot.
+ *
+ * Most access to this endpoint is via the post method.
+ * Here we will pick out the magic auth params which arrive as a get request,
+ * and the only communications to arrive this way.
+ *
  * Magic Auth
  * ==========
  *
@@ -24,75 +25,79 @@ function post_init(&$a) {
  * The endpoint is typically  https://$remotesite/post - or whatever was specified as the callback url in prior communications
  * (we will bootstrap an address and fetch a zot info packet if possible where no prior communications exist)
  *
- * Four GET parameters are supplied:
- *
- ** auth => the urlencoded webbie (channel@host.domain) of the channel requesting access
- ** dest => the desired destination URL (urlencoded)
- ** sec  => a random string which is also stored on $mysite for use during the verification phase. 
- ** version => the zot revision
+ * Five GET parameters are supplied:
+ * * auth => the urlencoded webbie (channel@host.domain) of the channel requesting access
+ * * dest => the desired destination URL (urlencoded)
+ * * sec  => a random string which is also stored on $mysite for use during the verification phase. 
+ * * version => the zot revision
+ * * delegate => optional urlencoded webbie of a local channel to invoke delegation rights for
  *
  * When this packet is received, an "auth-check" zot message is sent to $mysite.
  * (e.g. if $_GET['auth'] is foobar@podunk.edu, a zot packet is sent to the podunk.edu zot endpoint, which is typically /post)
  * If no information has been recorded about the requesting identity a zot information packet will be retrieved before
  * continuing.
- * 
+ *
  * The sender of this packet is an arbitrary/random site channel. The recipients will be a single recipient corresponding
  * to the guid and guid_sig we have associated with the requesting auth identity
  *
- *
- *    {
- *      "type":"auth_check",
- *      "sender":{
- *        "guid":"kgVFf_...",
- *        "guid_sig":"PT9-TApz...",
- *        "url":"http:\/\/podunk.edu",
- *        "url_sig":"T8Bp7j..."
- *      },
- *      "recipients":{
- *        {
- *        "guid":"ZHSqb...",
- *        "guid_sig":"JsAAXi..."
- *        }
- *      }
- *      "callback":"\/post",
- *      "version":1,
- *      "secret":"1eaa661",
- *      "secret_sig":"eKV968b1..."
- *    }
- *
+ * \code{.json}
+ * {
+ *   "type":"auth_check",
+ *   "sender":{
+ *     "guid":"kgVFf_...",
+ *     "guid_sig":"PT9-TApz...",
+ *     "url":"http:\/\/podunk.edu",
+ *     "url_sig":"T8Bp7j..."
+ *   },
+ *   "recipients":{
+ *     {
+ *       "guid":"ZHSqb...",
+ *       "guid_sig":"JsAAXi..."
+ *     }
+ *   }
+ *   "callback":"\/post",
+ *   "version":1,
+ *   "secret":"1eaa661",
+ *   "secret_sig":"eKV968b1..."
+ * }
+ * \endcode
  *
  * auth_check messages MUST use encapsulated encryption. This message is sent to the origination site, which checks the 'secret' to see 
  * if it is the same as the 'sec' which it passed originally. It also checks the secret_sig which is the secret signed by the 
  * destination channel's private key and base64url encoded. If everything checks out, a json packet is returned:
  *
- *    { 
- *      "success":1, 
- *      "confirm":"q0Ysovd1u..."
- *      "service_class":(optional)
- *      "level":(optional)
- *    }
+ * \code{.json}
+ * {
+ *   "success":1,
+ *   "confirm":"q0Ysovd1u...",
+ *   "service_class":(optional)
+ *   "level":(optional)
+ * }
+ * \endcode
  *
  * 'confirm' in this case is the base64url encoded RSA signature of the concatenation of 'secret' with the
  * base64url encoded whirlpool hash of the requestor's guid and guid_sig; signed with the source channel private key. 
  * This prevents a man-in-the-middle from inserting a rogue success packet. Upon receipt and successful 
  * verification of this packet, the destination site will redirect to the original destination URL and indicate a successful remote login. 
  * Service_class can be used by cooperating sites to provide different access rights based on account rights and subscription plans. It is 
- * a string whose contents are not defined by protocol. Example: "basic" or "gold". 
- *
- *
+ * a string whose contents are not defined by protocol. Example: "basic" or "gold".
  *
+ * @param[in,out] App &$a
  */
-	
-	if(array_key_exists('auth',$_REQUEST)) {
+function post_init(&$a) {
+
+	if (array_key_exists('auth', $_REQUEST)) {
 
 		$ret = array('success' => false, 'message' => '');
 
 		logger('mod_zot: auth request received.');
-		$address = $_REQUEST['auth'];
-		$desturl = $_REQUEST['dest'];
-		$sec     = $_REQUEST['sec'];
-		$version = $_REQUEST['version'];
-		$test    = ((x($_REQUEST,'test')) ? intval($_REQUEST['test']) : 0);
+		$address  = $_REQUEST['auth'];
+		$desturl  = $_REQUEST['dest'];
+		$sec      = $_REQUEST['sec'];
+		$version  = $_REQUEST['version'];
+		$delegate = $_REQUEST['delegate'];
+
+		$test     = ((x($_REQUEST, 'test')) ? intval($_REQUEST['test']) : 0);
 
 		// They are authenticating ultimately to the site and not to a particular channel.
 		// Any channel will do, providing it's currently active. We just need to have an 
@@ -102,10 +107,10 @@ function post_init(&$a) {
 			intval(PAGE_REMOVED)
 		);
 
-		if(! $c) {
+		if (! $c) {
 			// nobody here
 			logger('mod_zot: auth: unable to find a response channel');
-			if($test) {
+			if ($test) {
 				$ret['message'] .= 'no local channels found.' . EOL;
 				json_return_and_die($ret);
 			}
@@ -118,12 +123,12 @@ function post_init(&$a) {
 			dbesc($address)
 		);
 
-		if(! $x) {
+		if (! $x) {
 			// finger them if they can't be found. 
-			$ret = zot_finger($address,null);
-			if($ret['success']) {
-				$j = json_decode($ret['body'],true);
-				if($j)
+			$ret = zot_finger($address, null);
+			if ($ret['success']) {
+				$j = json_decode($ret['body'], true);
+				if ($j)
 					import_xchan($j);
 				$x = q("select * from hubloc left join xchan on xchan_hash = hubloc_hash where hubloc_addr = '%s' order by hubloc_id desc limit 1",
 					dbesc($address)
@@ -158,64 +163,65 @@ function post_init(&$a) {
 		// Also check that they are coming from the same site as they authenticated with originally.
 
 		$already_authed = ((($remote) && ($x[0]['hubloc_hash'] == $remote) && ($x[0]['hubloc_url'] === $_SESSION['remote_hub'])) ? true : false); 
+		if($delegate && $delegate !== $_SESSION['delegate_channel'])
+			$already_authed = false;
 
 		$j = array();
 
-		if(! $already_authed) {
+		if (! $already_authed) {
 
 			// Auth packets MUST use ultra top-secret hush-hush mode - e.g. the entire packet is encrypted using the site private key
 			// The actual channel sending the packet ($c[0]) is not important, but this provides a generic zot packet with a sender
 			// which can be verified
  
 			$p = zot_build_packet($c[0],$type = 'auth_check', array(array('guid' => $x[0]['hubloc_guid'],'guid_sig' => $x[0]['hubloc_guid_sig'])), $x[0]['hubloc_sitekey'], $sec);
-			if($test) {
+			if ($test) {
 				$ret['message'] .= 'auth check packet created using sitekey ' . $x[0]['hubloc_sitekey'] . EOL;
 				$ret['message'] .= 'packet contents: ' . $p . EOL;
 			}
 
 			$result = zot_zot($x[0]['hubloc_callback'],$p);
 
-
-			if(! $result['success']) {
+			if (! $result['success']) {
 				logger('mod_zot: auth_check callback failed.');
-				if($test) {
+				if ($test) {
 					$ret['message'] .= 'auth check request to your site returned .' . print_r($result, true) . EOL;
 					json_return_and_die($ret);
 				}
 
 				goaway($desturl);
 			}
-			$j = json_decode($result['body'],true);
-			if(! $j) {
+			$j = json_decode($result['body'], true);
+			if (! $j) {
 				logger('mod_zot: auth_check json data malformed.');
 				if($test) {
 					$ret['message'] .= 'json malformed: ' . $result['body'] . EOL;
 					json_return_and_die($ret);
 				}
-			}				
+			}
 		}
 
-		if($test) {
+		if ($test) {
 			$ret['message'] .= 'auth check request returned .' . print_r($j, true) . EOL;
-		}	
+		}
 
-		if($already_authed || $j['success']) {
-			if($j['success']) {
+		if ($already_authed || $j['success']) {
+			if ($j['success']) {
 				// legit response, but we do need to check that this wasn't answered by a man-in-middle
-				if(! rsa_verify($sec . $x[0]['xchan_hash'],base64url_decode($j['confirm']),$x[0]['xchan_pubkey'])) {
+				if (! rsa_verify($sec . $x[0]['xchan_hash'],base64url_decode($j['confirm']),$x[0]['xchan_pubkey'])) {
 					logger('mod_zot: auth: final confirmation failed.');
-					if($test) {
+					if ($test) {
 						$ret['message'] .= 'final confirmation failed. ' . $sec . print_r($j,true) . print_r($x[0],true);
 						json_return_and_die($ret);
 					}
-						
+
 					goaway($desturl);
 				}
-				if(array_key_exists('service_class',$j))
+				if (array_key_exists('service_class',$j))
 					$remote_service_class = $j['service_class'];
-				if(array_key_exists('level',$j))
+				if (array_key_exists('level',$j))
 					$remote_level = $j['level'];
-				if(array_key_exists('DNT',$j))
+				if (array_key_exists('DNT',$j))
 					$DNT = $j['DNT'];
 			}
 			// everything is good... maybe
@@ -224,35 +230,54 @@ function post_init(&$a) {
 				// tell them to logout if they're logged in locally as anything but the target remote account
 				// in which case just shut up because they don't need to be doing this at all.
 
-				if($a->channel['channel_hash'] != $x[0]['xchan_hash']) {
+				if ($a->channel['channel_hash'] != $x[0]['xchan_hash']) {
 					logger('mod_zot: auth: already authenticated locally as somebody else.');
 					notice( t('Remote authentication blocked. You are logged into this site locally. Please logout and retry.') . EOL);
-					if($test) {
+					if ($test) {
 						$ret['message'] .= 'already logged in locally with a conflicting identity.' . EOL;
 						json_return_and_die($ret);
 					}
-
 				}
 				goaway($desturl);
 			}
+
 			// log them in
 
-			if($test) {
+			if ($test) {
 				$ret['success'] = true;
 				$ret['message'] .= 'Authentication Success!' . EOL;
 				json_return_and_die($ret);
 			}
 
+			$delegation_success = false;
+			if ($delegate) {
+				$r = q("select * from channel left join xchan on channel_hash = xchan_hash where xchan_addr = '%s' limit 1",
+					dbesc($delegate)
+				);
+				if ($r && intval($r[0]['channel_id'])) {
+					$allowed = perm_is_allowed($r[0]['channel_id'],$x[0]['xchan_hash'],'delegate');
+					if ($allowed) {
+						$_SESSION['delegate_channel'] = $r[0]['channel_id'];
+						$_SESSION['delegate'] = $x[0]['xchan_hash'];
+						$_SESSION['account_id'] = intval($r[0]['channel_account_id']);
+						require_once('include/security.php');
+						change_channel($r[0]['channel_id']);
+						$delegation_success = true;
+					}
+				}
+			}
 
 			$_SESSION['authenticated'] = 1;
-			$_SESSION['visitor_id'] = $x[0]['xchan_hash'];
-			$_SESSION['my_url'] = $x[0]['xchan_url'];
-			$_SESSION['my_address'] = $address;
-			$_SESSION['remote_service_class'] = $remote_service_class;
-			$_SESSION['remote_level'] = $remote_level;
-			$_SESSION['remote_hub'] = $remote_hub;
-			$_SESSION['DNT'] = $DNT;
-			
+			if (! $delegation_success) {
+				$_SESSION['visitor_id'] = $x[0]['xchan_hash'];
+				$_SESSION['my_url'] = $x[0]['xchan_url'];
+				$_SESSION['my_address'] = $address;
+				$_SESSION['remote_service_class'] = $remote_service_class;
+				$_SESSION['remote_level'] = $remote_level;
+				$_SESSION['remote_hub'] = $remote_hub;
+				$_SESSION['DNT'] = $DNT;
+			}
+
 			$arr = array('xchan' => $x[0], 'url' => $desturl, 'session' => $_SESSION);
 			call_hooks('magic_auth_success',$arr);
 			$a->set_observer($x[0]);
@@ -260,22 +285,23 @@ function post_init(&$a) {
 			$a->set_groups(init_groups_visitor($_SESSION['visitor_id']));
 			info(sprintf( t('Welcome %s. Remote authentication successful.'),$x[0]['xchan_name']));
 			logger('mod_zot: auth success from ' . $x[0]['xchan_addr']); 
-
 		}
 		else {
 			if($test) {
 				$ret['message'] .= 'auth failure. ' . print_r($_REQUEST,true) . print_r($j,true) . EOL;
 				json_return_and_die($ret);
 			}
-
 			logger('mod_zot: magic-auth failure - not authenticated: ' . $x[0]['xchan_addr']);
 		}
 
-		// FIXME - we really want to save the return_url in the session before we visit rmagic.
-		// This does however prevent a recursion if you visit rmagic directly, as it would otherwise send you back here again. 
-		// But z_root() probably isn't where you really want to go. 
+		/**
+		 * @FIXME we really want to save the return_url in the session before we
+		 * visit rmagic. This does however prevent a recursion if you visit
+		 * rmagic directly, as it would otherwise send you back here again.
+		 * But z_root() probably isn't where you really want to go.
+		 */
 
-		if($test) {
+		if ($test) {
 			$ret['message'] .= 'auth failure fallthrough ' . print_r($_REQUEST,true) . print_r($j,true) . EOL;
 			json_return_and_die($ret);
 		}
@@ -285,41 +311,40 @@ function post_init(&$a) {
 
 		goaway($desturl);
 	}
-	return;
 }
 
 
 /**
- * @function post_post(&$a)
- *     zot communications and messaging
+ * @brief zot communications and messaging.
  *
- *     Sender HTTP posts to this endpoint ($site/post typically) with 'data' parameter set to json zot message packet.
- *     This packet is optionally encrypted, which we will discover if the json has an 'iv' element.
- *     $contents => array( 'alg' => 'aes256cbc', 'iv' => initialisation vector, 'key' => decryption key, 'data' => encrypted data);
- *     $contents->iv and $contents->key are random strings encrypted with this site's RSA public key and then base64url encoded.
- *     Currently only 'aes256cbc' is used, but this is extensible should that algorithm prove inadequate.
+ * Sender HTTP posts to this endpoint ($site/post typically) with 'data' parameter set to json zot message packet.
+ * This packet is optionally encrypted, which we will discover if the json has an 'iv' element.
+ * $contents => array( 'alg' => 'aes256cbc', 'iv' => initialisation vector, 'key' => decryption key, 'data' => encrypted data);
+ * $contents->iv and $contents->key are random strings encrypted with this site's RSA public key and then base64url encoded.
+ * Currently only 'aes256cbc' is used, but this is extensible should that algorithm prove inadequate.
  *
- *     Once decrypted, one will find the normal json_encoded zot message packet. 
+ * Once decrypted, one will find the normal json_encoded zot message packet.
  * 
  * Defined packet types are: notify, purge, refresh, force_refresh, auth_check, ping, and pickup 
  *
  * Standard packet: (used by notify, purge, refresh, force_refresh, and auth_check)
- *
+ * \code{.json}
  * {
- *  "type": "notify",
- *  "sender":{
- *       "guid":"kgVFf_1...",
- *       "guid_sig":"PT9-TApzp...",
- *       "url":"http:\/\/podunk.edu",
- *       "url_sig":"T8Bp7j5...",
- *    },
- *  "recipients": { optional recipient array },
- *  "callback":"\/post",
- *  "version":1,
- *  "secret":"1eaa...",
- *  "secret_sig": "df89025470fac8..."
+ *   "type": "notify",
+ *   "sender":{
+ *     "guid":"kgVFf_1...",
+ *     "guid_sig":"PT9-TApzp...",
+ *     "url":"http:\/\/podunk.edu",
+ *     "url_sig":"T8Bp7j5...",
+ *   },
+ *   "recipients": { optional recipient array },
+ *   "callback":"\/post",
+ *   "version":1,
+ *   "secret":"1eaa...",
+ *   "secret_sig": "df89025470fac8..."
  * }
- * 
+ * \endcode
+ *
  * Signature fields are all signed with the sender channel private key and base64url encoded.
  * Recipients are arrays of guid and guid_sig, which were previously signed with the recipients private 
  * key and base64url encoded and later obtained via channel discovery. Absence of recipients indicates
@@ -327,108 +352,116 @@ function post_init(&$a) {
  *
  * "pickup" packet:
  * The pickup packet is sent in response to a notify packet from another site
- * 
+ * \code{.json}
  * {
- *  "type":"pickup",
- *  "url":"http:\/\/example.com",
- *  "callback":"http:\/\/example.com\/post",
- *  "callback_sig":"teE1_fLI...",
- *  "secret":"1eaa...",
- *  "secret_sig":"O7nB4_..."
+ *   "type":"pickup",
+ *   "url":"http:\/\/example.com",
+ *   "callback":"http:\/\/example.com\/post",
+ *   "callback_sig":"teE1_fLI...",
+ *   "secret":"1eaa...",
+ *   "secret_sig":"O7nB4_..."
  * }
+ * \endcode
  *
- * In the pickup packet, the sig fields correspond to the respective data element signed with this site's system 
- * private key and then base64url encoded.
+ * In the pickup packet, the sig fields correspond to the respective data
+ * element signed with this site's system private key and then base64url encoded.
  * The "secret" is the same as the original secret from the notify packet. 
  *
- * If verification is successful, a json structure is returned
- * containing a success indicator and an array of type 'pickup'.
- * Each pickup element contains the original notify request and a message field whose contents are 
- * dependent on the message type
+ * If verification is successful, a json structure is returned containing a
+ * success indicator and an array of type 'pickup'.
+ * Each pickup element contains the original notify request and a message field
+ * whose contents are dependent on the message type.
  *
- * This JSON array is AES encapsulated using the site public key of the site that sent the initial zot pickup packet.
+ * This JSON array is AES encapsulated using the site public key of the site
+ * that sent the initial zot pickup packet.
  * Using the above example, this would be example.com.
- * 
- * 
+ *
+ * \code{.json}
  * {
- * "success":1,
- * "pickup":{
- *   "notify":{
- *     "type":"notify",
- *     "sender":{
- *       "guid":"kgVFf_...",
- *       "guid_sig":"PT9-TApz...",
- *       "url":"http:\/\/z.podunk.edu",
- *       "url_sig":"T8Bp7j5D..."
- *     },
- *     "callback":"\/post",
- *     "version":1,
- *     "secret":"1eaa661..."
- *   },
- *   "message":{
- *     "type":"activity",
- *     "message_id":"10b049ce384cbb2da9467319bc98169ab36290b8bbb403aa0c0accd9cb072e76@podunk.edu",
- *     "message_top":"10b049ce384cbb2da9467319bc98169ab36290b8bbb403aa0c0accd9cb072e76@podunk.edu",
- *     "message_parent":"10b049ce384cbb2da9467319bc98169ab36290b8bbb403aa0c0accd9cb072e76@podunk.edu",
- *     "created":"2012-11-20 04:04:16",
- *     "edited":"2012-11-20 04:04:16",
- *     "title":"",
- *     "body":"Hi Nickordo",
- *     "app":"",
- *     "verb":"post",
- *     "object_type":"",
- *     "target_type":"",
- *     "permalink":"",
- *     "location":"",
- *     "longlat":"",
- *     "owner":{
- *       "name":"Indigo",
- *       "address":"indigo@podunk.edu",
- *       "url":"http:\/\/podunk.edu",
- *       "photo":{
- *         "mimetype":"image\/jpeg",
- *         "src":"http:\/\/podunk.edu\/photo\/profile\/m\/5"
+ *   "success":1,
+ *   "pickup":{
+ *     "notify":{
+ *       "type":"notify",
+ *       "sender":{
+ *         "guid":"kgVFf_...",
+ *         "guid_sig":"PT9-TApz...",
+ *         "url":"http:\/\/z.podunk.edu",
+ *         "url_sig":"T8Bp7j5D..."
  *       },
- *       "guid":"kgVFf_...",
- *       "guid_sig":"PT9-TAp...",
+ *       "callback":"\/post",
+ *       "version":1,
+ *       "secret":"1eaa661..."
  *     },
- *     "author":{
- *       "name":"Indigo",
- *       "address":"indigo@podunk.edu",
- *       "url":"http:\/\/podunk.edu",
- *       "photo":{
- *         "mimetype":"image\/jpeg",
- *         "src":"http:\/\/podunk.edu\/photo\/profile\/m\/5"
+ *     "message":{
+ *       "type":"activity",
+ *       "message_id":"10b049ce384cbb2da9467319bc98169ab36290b8bbb403aa0c0accd9cb072e76@podunk.edu",
+ *       "message_top":"10b049ce384cbb2da9467319bc98169ab36290b8bbb403aa0c0accd9cb072e76@podunk.edu",
+ *       "message_parent":"10b049ce384cbb2da9467319bc98169ab36290b8bbb403aa0c0accd9cb072e76@podunk.edu",
+ *       "created":"2012-11-20 04:04:16",
+ *       "edited":"2012-11-20 04:04:16",
+ *       "title":"",
+ *       "body":"Hi Nickordo",
+ *       "app":"",
+ *       "verb":"post",
+ *       "object_type":"",
+ *       "target_type":"",
+ *       "permalink":"",
+ *       "location":"",
+ *       "longlat":"",
+ *       "owner":{
+ *         "name":"Indigo",
+ *         "address":"indigo@podunk.edu",
+ *         "url":"http:\/\/podunk.edu",
+ *         "photo":{
+ *           "mimetype":"image\/jpeg",
+ *           "src":"http:\/\/podunk.edu\/photo\/profile\/m\/5"
+ *         },
+ *         "guid":"kgVFf_...",
+ *         "guid_sig":"PT9-TAp...",
  *       },
- *       "guid":"kgVFf_...",
- *       "guid_sig":"PT9-TAp..."
+ *       "author":{
+ *         "name":"Indigo",
+ *         "address":"indigo@podunk.edu",
+ *         "url":"http:\/\/podunk.edu",
+ *         "photo":{
+ *           "mimetype":"image\/jpeg",
+ *           "src":"http:\/\/podunk.edu\/photo\/profile\/m\/5"
+ *         },
+ *         "guid":"kgVFf_...",
+ *         "guid_sig":"PT9-TAp..."
+ *       }
  *     }
  *   }
  * }
- *} 
+ * \endcode
  *
- * Currently defined message types are 'activity', 'mail', 'profile', 'location' and 'channel_sync', 
- * which each have different content schemas.
+ * Currently defined message types are 'activity', 'mail', 'profile', 'location'
+ * and 'channel_sync', which each have different content schemas.
  *
  * Ping packet:
- * A ping packet does not require any parameters except the type. It may or may not be encrypted.
- * 
+ * A ping packet does not require any parameters except the type. It may or may
+ * not be encrypted.
+ *
+ * \code{.json}
  * {
- *  "type": "ping"
+ *   "type": "ping"
  * }
- * 
+ * \endcode
+ *
  * On receipt of a ping packet a ping response will be returned:
  *
+ * \code{.json}
  * {
  *   "success" : 1,
  *   "site" {
- *       "url":"http:\/\/podunk.edu",
- *       "url_sig":"T8Bp7j5...",
- *       "sitekey": "-----BEGIN PUBLIC KEY-----
- *                  MIICIjANBgkqhkiG9w0BAQE..."
- *    }
+ *     "url": "http:\/\/podunk.edu",
+ *     "url_sig": "T8Bp7j5...",
+ *     "sitekey": "-----BEGIN PUBLIC KEY-----
+ *                 MIICIjANBgkqhkiG9w0BAQE..."
+ *   }
  * }
- * 
+ * \endcode
+ *
  * The ping packet can be used to verify that a site has not been re-installed, and to 
  * initiate corrective action if it has. The url_sig is signed with the site private key
  * and base64url encoded - and this should verify with the enclosed sitekey. Failure to
@@ -442,24 +475,22 @@ function post_init(&$a) {
  * If you have no records which match this url_sig and key - no corrective action should
  * be taken as this packet may have been returned by an imposter.  
  *
+ * @param[in,out] App &$a
  */
-
-	
 function post_post(&$a) {
 
-
 	$encrypted_packet = false;
 	$ret = array('success' => false);
 
 	$data = json_decode($_REQUEST['data'],true);
 
-
-	/**
-	 * Many message packets will arrive encrypted. The existence of an 'iv' element 
-	 * tells us we need to unencapsulate the AES-256-CBC content using the site private key
+	/*
+	 * Many message packets will arrive encrypted. The existence of an 'iv'
+	 * element tells us we need to unencapsulate the AES-256-CBC content using
+	 * the site private key.
 	 */
 
-	if(array_key_exists('iv',$data)) {
+	if($data && array_key_exists('iv',$data)) {
 		$encrypted_packet = true;
 		$data = crypto_unencapsulate($data,get_config('system','prvkey'));
 		logger('mod_zot: decrypt1: ' . $data, LOGGER_DATA);
@@ -502,12 +533,11 @@ function post_post(&$a) {
 
 	if($msgtype === 'pickup') {
 
-		/**
+		/*
 		 * The 'pickup' message arrives with a tracking ID which is associated with a particular outq_hash
 		 * First verify that that the returned signatures verify, then check that we have an outbound queue item
 		 * with the correct hash.
 		 * If everything verifies, find any/all outbound messages in the queue for this hubloc and send them back
-		 *
 		 */
 
 		if((! $data['secret']) || (! $data['secret_sig'])) {
@@ -560,7 +590,7 @@ function post_post(&$a) {
 			json_return_and_die($ret);
 		}
 
-		/**
+		/*
 		 * If we made it to here, the signatures verify, but we still don't know if the tracking ID is valid.
 		 * It wouldn't be an error if the tracking ID isn't found, because we may have sent this particular
 		 * queue item with another pickup (after the tracking ID for the other pickup  was verified). 
@@ -576,7 +606,7 @@ function post_post(&$a) {
 			json_return_and_die($ret);
 		}
 
-		/**
+		/*
 		 * Everything is good if we made it here, so find all messages that are going to this location
 		 * and send them all.
 		 */
@@ -585,7 +615,7 @@ function post_post(&$a) {
 			dbesc($data['callback'])
 		);
 		if($r) {
-			logger('mod_zot: succesful pickup message received from ' . $data['callback'] . ' ' . count($r) . ' message(s) picked up', LOGGER_DEBUG);
+			logger('mod_zot: successful pickup message received from ' . $data['callback'] . ' ' . count($r) . ' message(s) picked up', LOGGER_DEBUG);
 
 			$ret['success'] = true;
 			$ret['pickup'] = array();
@@ -614,33 +644,31 @@ function post_post(&$a) {
 		$encrypted = crypto_encapsulate(json_encode($ret),$sitekey);
 		json_return_and_die($encrypted);
 
-		/** pickup: end */
+		/* pickup: end */
 	}
 
 
-
-
-	/**
+	/*
 	 * All other message types require us to verify the sender. This is a generic check, so we 
 	 * will do it once here and bail if anything goes wrong.
 	 */
 
-	if(array_key_exists('sender',$data)) {
+	if (array_key_exists('sender',$data)) {
 		$sender = $data['sender'];
-	}	
+	}
 
-	/** Check if the sender is already verified here */
+	/* Check if the sender is already verified here */
 
 	$hub = zot_gethub($sender);
 
-	if(! $hub) {
+	if (! $hub) {
 
-		/** Have never seen this guid or this guid coming from this location. Check it and register it. */
+		/* Have never seen this guid or this guid coming from this location. Check it and register it. */
 
 		// (!!) this will validate the sender
 		$result = zot_register_hub($sender);
 
-		if((! $result['success']) || (! ($hub = zot_gethub($sender)))) {
+		if ((! $result['success']) || (! ($hub = zot_gethub($sender)))) {
 			$ret['message'] = 'Hub not available.';
 			logger('mod_zot: no hub');
 			json_return_and_die($ret);
@@ -670,15 +698,13 @@ function post_post(&$a) {
 		q("update xchan set xchan_orphan = 0 where xchan_orphan = 1 and xchan_hash = '%s'",
 			dbesc($hub['hubloc_hash'])
 		);
-	} 
-
+	}
 
 
-	/** 
+	/*
 	 * This hub has now been proven to be valid.
 	 * Any hub with the same URL and a different sitekey cannot be valid.
 	 * Get rid of them (mark them deleted). There's a good chance they were re-installs.
-	 *
 	 */
 
 	q("update hubloc set hubloc_deleted = 1 where hubloc_url = '%s' and hubloc_sitekey != '%s' ",
@@ -686,15 +712,15 @@ function post_post(&$a) {
 		dbesc($hub['hubloc_sitekey'])
 	);
 
-	// TODO: check which hub is primary and take action if mismatched
+	/** @TODO check which hub is primary and take action if mismatched */
 
-	if(array_key_exists('recipients',$data))
+	if (array_key_exists('recipients', $data))
 		$recipients = $data['recipients'];
 
 
-	if($msgtype === 'auth_check') {
+	if ($msgtype === 'auth_check') {
 
-		/**
+		/*
 		 * Requestor visits /magic/?dest=somewhere on their own site with a browser
 		 * magic redirects them to $destsite/post [with auth args....]
 		 * $destsite sends an auth_check packet to originator site
@@ -709,12 +735,12 @@ function post_post(&$a) {
 		 */
 		logger('mod_zot: auth_check', LOGGER_DEBUG);
 
-		if(! $encrypted_packet) {
+		if (! $encrypted_packet) {
 			logger('mod_zot: auth_check packet was not encrypted.');
 			$ret['message'] .= 'no packet encryption' . EOL;
 			json_return_and_die($ret);
 		}
-		
+
 		$arr = $data['sender'];
 		$sender_hash = make_xchan_hash($arr['guid'],$arr['guid_sig']);
 
@@ -732,7 +758,7 @@ function post_post(&$a) {
 		// First verify their signature. We will have obtained a zot-info packet from them as part of the sender
 		// verification. 
 
-		if((! $y) || (! rsa_verify($data['secret'],base64url_decode($data['secret_sig']),$y[0]['xchan_pubkey']))) {
+		if ((! $y) || (! rsa_verify($data['secret'], base64url_decode($data['secret_sig']),$y[0]['xchan_pubkey']))) {
 			logger('mod_zot: auth_check: sender not found or secret_sig invalid.');
 			$ret['message'] .= 'sender not found or sig invalid ' . print_r($y,true) . EOL;
 			json_return_and_die($ret);
@@ -742,14 +768,14 @@ function post_post(&$a) {
 
 		$ret['message'] .= 'recipients ' . print_r($recipients,true) . EOL;
 
-		if($data['recipients']) {
+		if ($data['recipients']) {
 
 			$arr = $data['recipients'][0];
-			$recip_hash = make_xchan_hash($arr['guid'],$arr['guid_sig']);
+			$recip_hash = make_xchan_hash($arr['guid'], $arr['guid_sig']);
 			$c = q("select channel_id, channel_account_id, channel_prvkey from channel where channel_hash = '%s' limit 1",
 				dbesc($recip_hash)
 			);
-			if(! $c) {
+			if (! $c) {
 				logger('mod_zot: auth_check: recipient channel not found.');
 				$ret['message'] .= 'recipient not found.' . EOL;
 				json_return_and_die($ret);
@@ -765,7 +791,7 @@ function post_post(&$a) {
 				dbesc($data['secret']),
 				dbesc($data['sender']['url'])
 			);
-			if(! $z) {
+			if (! $z) {
 				logger('mod_zot: auth_check: verification key not found.');
 				$ret['message'] .= 'verification key not found' . EOL;
 				json_return_and_die($ret);
@@ -781,70 +807,66 @@ function post_post(&$a) {
 			logger('mod_zot: auth_check: success', LOGGER_DEBUG);
 			$ret['success'] = true;
 			$ret['confirm'] = $confirm;
-			if($u && $u[0]['account_service_class'])
+			if ($u && $u[0]['account_service_class'])
 				$ret['service_class'] = $u[0]['account_service_class'];
 
 			// Set "do not track" flag if this site or this channel's profile is restricted
 			// in some way
 
-			if(intval(get_config('system','block_public')))
+			if (intval(get_config('system','block_public')))
 				$ret['DNT'] = true;
-			if(! perm_is_allowed($c[0]['channel_id'],'','view_profile'))
+			if (! perm_is_allowed($c[0]['channel_id'],'','view_profile'))
 				$ret['DNT'] = true;
-			if(get_pconfig($c[0]['channel_id'],'system','do_not_track'))
+			if (get_pconfig($c[0]['channel_id'],'system','do_not_track'))
 				$ret['DNT'] = true;
-			if(get_pconfig($c[0]['channel_id'],'system','hide_online_status'))
+			if (get_pconfig($c[0]['channel_id'],'system','hide_online_status'))
 				$ret['DNT'] = true;
 
 			json_return_and_die($ret);
-
 		}
 		json_return_and_die($ret);
 	}
 
-	if($msgtype === 'request') {
+	if ($msgtype === 'request') {
 		// request a particular post/conversation by message_id
 		$x = zot_process_message_request($data);
 		json_return_and_die($x);		
 	}
 
-
-	if($msgtype === 'purge') {
-		if($recipients) {
+	if ($msgtype === 'purge') {
+		if ($recipients) {
 			// basically this means "unfriend"
-			foreach($recipients as $recip) {
+			foreach ($recipients as $recip) {
 				$r = q("select channel.*,xchan.* from channel 
 					left join xchan on channel_hash = xchan_hash
 					where channel_guid = '%s' and channel_guid_sig = '%s' limit 1",
 					dbesc($recip['guid']),
 					dbesc($recip['guid_sig'])
 				);
-				if($r) {
+				if ($r) {
 					$r = q("select abook_id from abook where uid = %d and abook_xchan = '%s' limit 1",
 						intval($r[0]['channel_id']),
 						dbesc(make_xchan_hash($sender['guid'],$sender['guid_sig']))
 					);
-					if($r) {
+					if ($r) {
 						contact_remove($r[0]['channel_id'],$r[0]['abook_id']);
 					}
 				}
 			}
-		}
-		else {
+		} else {
 			// Unfriend everybody - basically this means the channel has committed suicide
 			$arr = $data['sender'];
 			$sender_hash = make_xchan_hash($arr['guid'],$arr['guid_sig']);
-		
+
 			require_once('include/Contact.php');
 			remove_all_xchan_resources($sender_hash);	
 
 			$ret['success'] = true;
 			json_return_and_die($ret);
-
 		}
 	}
 
-	if(($msgtype === 'refresh') || ($msgtype === 'force_refresh')) {
+	if (($msgtype === 'refresh') || ($msgtype === 'force_refresh')) {
 
 		// remote channel info (such as permissions or photo or something)
 		// has been updated. Grab a fresh copy and sync it.
@@ -852,11 +874,11 @@ function post_post(&$a) {
 		// force_refresh unconditionally creates a directory update record,
 		// even if no changes were detected upon processing.
 
-		if($recipients) {
+		if ($recipients) {
 
 			// This would be a permissions update, typically for one connection
 
-			foreach($recipients as $recip) {	
+			foreach ($recipients as $recip) {
 				$r = q("select channel.*,xchan.* from channel 
 					left join xchan on channel_hash = xchan_hash
 					where channel_guid = '%s' and channel_guid_sig = '%s' limit 1",
@@ -868,44 +890,41 @@ function post_post(&$a) {
 						'xchan_guid'     => $sender['guid'], 
 						'xchan_guid_sig' => $sender['guid_sig'],
 						'hubloc_url'     => $sender['url']
-				),$r[0], (($msgtype === 'force_refresh') ? true : false));
+				), $r[0], (($msgtype === 'force_refresh') ? true : false));
 			}
-		}
-		else {
+		} else {
 
 			// system wide refresh
-				
+
 			$x = zot_refresh(array(
 				'xchan_guid'     => $sender['guid'], 
 				'xchan_guid_sig' => $sender['guid_sig'],
 				'hubloc_url'     => $sender['url']
-			),null,(($msgtype === 'force_refresh') ? true : false));
+			), null, (($msgtype === 'force_refresh') ? true : false));
 		}
 		$ret['success'] = true;
 		json_return_and_die($ret);
 	}
 
-	if($msgtype === 'notify') {
+	if ($msgtype === 'notify') {
+
+		logger('notify received from ' . $hub['hubloc_url']);
+
+
 		$async = get_config('system','queued_fetch');
 
-		if($async) {
+		if ($async) {
 			// add to receive queue
 			// qreceive_add($data);
-		}
-		else {
+		} else {
 			$x = zot_fetch($data);
 			$ret['delivery_report'] = $x;
 		}
 
 		$ret['success'] = true;
 		json_return_and_die($ret);
-
 	}
 
-
 	// catchall
 	json_return_and_die($ret);
-
-
 }
-