diff --git a/browserid/lib/db.js b/browserid/lib/db.js
index 798e78b1d896c3a7f8189116c736bbf7f5206b2b..8a0be8d44557bf9fa1250d3df813b8e6c04e5455 100644
--- a/browserid/lib/db.js
+++ b/browserid/lib/db.js
@@ -36,6 +36,9 @@ setTimeout(function() {
   });
 }, 0);
 
+// accepts a function that will be invoked once the database is ready for transactions.
+// this hook is important to pause the rest of application startup until async database
+// connection establishment is complete.
 exports.onReady = function(f) {
   setTimeout(function() {
     if (ready) f();
diff --git a/browserid/tests/db-test.js b/browserid/tests/db-test.js
index 61a70d4faa5a48ffdb5ea695fadd4a96d4ec9db8..773ecc73e8fad870226f8ff3d3f5668e1380e9fd 100755
--- a/browserid/tests/db-test.js
+++ b/browserid/tests/db-test.js
@@ -24,6 +24,106 @@ suite.addBatch({
 
 // XXX: add exhaustive tests of the db API here
 
+var secret = undefined;
+
+suite.addBatch({
+  "an email address is not reported as staged before it is": {
+    topic: function() {
+      return db.isStaged('lloyd@nowhe.re');
+    },
+    "isStaged returns false": function (e, r) {
+      assert.strictEqual(r, false);
+    }
+  },
+  "an email address is not reported as known before it is": {
+    topic: function() {
+      db.emailKnown('lloyd@nowhe.re', this.callback);
+    },
+    "emailKnown returns false": function (e, r) {
+      assert.strictEqual(r, false);
+    }
+  }
+});
+
+suite.addBatch({
+  "stage a user for creation pending verification": {
+    topic: function() {
+      return secret = db.stageUser({
+        email: 'lloyd@nowhe.re',
+        pubkey: 'fakepublickey',
+        pass: 'fakepasswordhash'
+      });
+    },
+    "staging returns a valid secret": function(e, r) {
+      assert.isString(secret);
+      assert.strictEqual(secret.length, 48);
+    }
+  }
+});
+
+suite.addBatch({
+  "an email address is reported": {
+    topic: function() {
+      return db.isStaged('lloyd@nowhe.re');
+    },
+    " as staged after it is": function (e, r) {
+      assert.strictEqual(r, true);
+    }
+  },
+  "an email address is not reported": {
+    topic: function() {
+      db.emailKnown('lloyd@nowhe.re', this.callback);
+    },
+    " as known when it is only staged": function (e, r) {
+      assert.strictEqual(r, false);
+    }
+  }
+});
+
+suite.addBatch({
+  "upon receipt of a secret": {
+    topic: function() {
+      db.gotVerificationSecret(secret, this.callback);
+    },
+    "gotVerificationSecret completes without error": function (e, r) {
+      assert.strictEqual(r, undefined);
+    }
+  }
+});
+
+suite.addBatch({
+  "an email address is not reported": {
+    topic: function() {
+      return db.isStaged('lloyd@nowhe.re');
+    },
+    "as staged immediately after its verified": function (e, r) {
+      assert.strictEqual(r, false);
+    }
+  },
+  "an email address is known": {
+    topic: function() {
+      db.emailKnown('lloyd@nowhe.re', this.callback);
+    },
+    "when it is": function (e, r) {
+      assert.strictEqual(r, true);
+    }
+  }
+});
+
+// XXX: remaining APIs to test 
+// exports.findByEmail
+// exports.addEmailToAccount
+// exports.addKeyToEmail
+// exports.cancelAccount
+// exports.checkAuth
+// exports.checkAuthHash
+// exports.emailsBelongToSameAccount
+// exports.getSyncResponse
+// exports.pubkeysForEmail
+// exports.removeEmail
+// exports.stageEmail
+
+
 suite.addBatch({
   "remove the database file": {
     topic: function() {