doco

3 files changed, 106 insertions, 11 deletions

diff --git a/include/poller.php b/include/poller.php
index 6f4736855..1dd065196 100644
--- a/include/poller.php
+++ b/include/poller.php
@@ -30,8 +30,8 @@ function poller_run($argv, $argc){
 	// expire any expired accounts
 
 	q("UPDATE account 
-		SET account_flags = account_flags | %d 
-		where not account_flags & %d 
+		SET account_flags = (account_flags | %d) 
+		where not (account_flags & %d) 
 		and account_expires != '0000-00-00 00:00:00' 
 		and account_expires < UTC_TIMESTAMP() ",
 		intval(ACCOUNT_EXPIRED),
@@ -56,6 +56,10 @@ function poller_run($argv, $argc){
 		proc_run('php','include/expire.php');
 	}
 
+	// If this is a directory server, request a sync with an upstream
+	// directory at least once a day, up to once every poll interval. 
+	// Pull remote changes and push local changes.
+	// potential issue: how do we keep from creating an endless update loop? 
 
 	$manual_id  = 0;
 	$generation = 0;
diff --git a/include/zot.php b/include/zot.php
index 7c54e5239..78978bbf9 100644
--- a/include/zot.php
+++ b/include/zot.php
@@ -47,6 +47,9 @@ function zot_get_hubloc($arr,$primary = false) {
 
 }
 	 
+/**
+ * obsolete
+
 function zot_notify($channel,$url,$type = 'notify',$recipients = null, $remote_key = null) {
 
 	$params = array(
@@ -74,6 +77,9 @@ function zot_notify($channel,$url,$type = 'notify',$recipients = null, $remote_k
 	$x = z_post_url($url,$params);
 	return($x);
 }
+*/
+
+
 
 /*
  *
@@ -117,10 +123,33 @@ function zot_build_packet($channel,$type = 'notify',$recipients = null, $remote_
 }
 
 
+/**
+ * @function: zot_zot
+ * @param: string $url
+ * @param: array $data
+ *
+ * @returns: array => see z_post_url for returned data format
+ */
+ 
+
+
 function zot_zot($url,$data) {
 	return z_post_url($url,array('data' => $data));
 }
 
+/**
+ * @function: zot_finger
+ *
+ * Look up information about channel
+ * @param: string $webbie
+ *   does not have to be host qualified e.g. 'foo' is treated as 'foo@thishub'
+ * @param: array $channel
+ *   (optional), if supplied permissions will be enumerated specifically for $channel
+ *
+ * @returns: array => see z_post_url and mod/zfinger.php
+ */
+
+
 function zot_finger($webbie,$channel) {
 
 
@@ -191,6 +220,15 @@ function zot_finger($webbie,$channel) {
 
 }
 
+/**
+ * @function: zot_refresh
+ *
+ * zot_refresh is typically invoked when somebody has changed permissions of a channel and they are notified
+ * to fetch new permissions via a finger operation. This may result in a new connection (abook entry) being added to a local channel
+ * and it may result in auto-permissions being granted. 
+ *
+ */
+
 function zot_refresh($them,$channel = null) {
 
 	logger('zot_refresh: them: ' . print_r($them,true), LOGGER_DATA);
@@ -360,6 +398,15 @@ function zot_refresh($them,$channel = null) {
 	return false;
 }
 
+/**
+ * @function: zot_gethub
+ *
+ * A guid and a url, both signed by the sender, distinguish a known sender at a known location
+ * This function looks these up to see if the channel is known. If not, we will need to verify it.
+ * @returns: array => hubloc record
+ */
+
+
 		
 function zot_gethub($arr) {
 
@@ -649,6 +696,18 @@ function zot_process_response($hub,$arr,$outq) {
 	logger('zot_process_response: ' . print_r($x,true), LOGGER_DATA);
 }
 
+/**
+ * @function: zot_fetch
+ *
+ * We received a notification packet (in mod/post.php) that a message is waiting for us, and we've verified the sender.
+ * Now send back a pickup message, using our message tracking ID ($arr['secret']), which we will sign.
+ * The entire pickup message is encrypted with the remote site's public key. 
+ * If everything checks out on the remote end, we will receive back a packet containing one or more messages,
+ * which will be processed before returning.
+ * 
+ */
+ 
+
 function zot_fetch($arr) {
 
 	logger('zot_fetch: ' . print_r($arr,true), LOGGER_DATA);
@@ -657,7 +716,7 @@ function zot_fetch($arr) {
 
 	$ret_hub = zot_gethub($arr['sender']);
 	if(! $ret_hub) {
-		logger('zot_fetch: not ret_hub');
+		logger('zot_fetch: no hub: ' . print_r($arr['sender'],true));
 		return;
 	}
 	
diff --git a/mod/post.php b/mod/post.php
index af08d3f98..d061a7078 100644
--- a/mod/post.php
+++ b/mod/post.php
@@ -137,7 +137,7 @@ function post_post(&$a) {
 
 	logger('mod_zot: ' . print_r($_REQUEST,true), LOGGER_DEBUG);
 
-	$ret = array('result' => false);
+	$ret = array('success' => false);
 
 	$data = json_decode($_REQUEST['data'],true);
 
@@ -156,6 +156,14 @@ 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'])) {
 			$ret['message'] = 'no verification signature';
 			logger('mod_zot: pickup: ' . $ret['message'], LOGGER_DEBUG);
@@ -172,7 +180,7 @@ function post_post(&$a) {
 		}
 		// verify the url_sig
 		$sitekey = $r[0]['hubloc_sitekey'];
-		logger('sitekey: ' . $sitekey);
+//		logger('sitekey: ' . $sitekey);
 
 		if(! rsa_verify($data['callback'],base64url_decode($data['callback_sig']),$sitekey)) {
 			$ret['message'] = 'possible site forgery';
@@ -186,7 +194,11 @@ function post_post(&$a) {
 			json_return_and_die($ret);
 		}
 
-		// If we made it to here, we've got a valid pickup. Grab everything for this host and send it.
+		/**
+		 * 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). 
+		 */
 
 		$r = q("select outq_posturl from outq where outq_hash = '%s' and outq_posturl = '%s' limit 1",
 			dbesc($data['secret']),
@@ -198,6 +210,11 @@ 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.
+		 */
+
 		$r = q("select * from outq where outq_posturl = '%s'",
 			dbesc($data['callback'])
 		);
@@ -214,16 +231,31 @@ function post_post(&$a) {
 		}
 		$encrypted = aes_encapsulate(json_encode($ret),$sitekey);
 		json_return_and_die($encrypted);
+
+		/** 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)) {
 		$sender = $data['sender'];
 	}	
 
+	/** Check if the sender is already verified here */
+
 	$hub = zot_gethub($sender);
+
 	if(! $hub) {
+
+		/** 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']) || (! zot_gethub($sender))) {
 			$ret['message'] = 'Hub not available.';
 			logger('mod_zot: no hub');
@@ -249,14 +281,14 @@ function post_post(&$a) {
 
 		}
 		else {
-			// basically this means the channel has committed suicide
+			// Unfriend everybody - basically this means the channel has committed suicide
 			$arr = $data['sender'];
 			$sender_hash = base64url_encode(hash('whirlpool',$arr['guid'] . $arr['guid_sig'], true));
 		
 			require_once('include/Contact.php');
 			remove_all_xchan_resources($sender_hash);	
 
-			$ret['result'] = true;
+			$ret['success'] = true;
 			json_return_and_die($ret);
 
 		}
@@ -296,7 +328,7 @@ function post_post(&$a) {
 				'hubloc_url'     => $sender['url']
 			),null);
 		}
-		$ret['result'] = true;
+		$ret['success'] = true;
 		json_return_and_die($ret);
 	}
 
@@ -312,7 +344,7 @@ function post_post(&$a) {
 			$ret['delivery_report'] = $x;
 		}
 
-		$ret['result'] = true;
+		$ret['success'] = true;
 		json_return_and_die($ret);
 
 	}
@@ -366,7 +398,7 @@ function post_post(&$a) {
 			);
 
 			logger('mod_zot: auth_check: success', LOGGER_DEBUG);
-			$ret['result'] = true;
+			$ret['success'] = true;
 			json_return_and_die($ret);
 
 		}