Refactor the interface to side-effect free

After attempting to use the interface for the first time, I found that it
was not very suitable. Implementing the large Store interface was also
painful.

The new interface is much more functional. All methods are side-effect free,
with the exception of calling the remaining store methods.

I've moved the trust check out of Axolotl as this should be done at a
higher level, in my opinion.

I've also removed the JSON serialisation of the session, as some clients may
want to serialise the session in other ways.

Author: joebandenburg

README.md

@@ -108,90 +108,13 @@ Name|Type|Description
 :---|:---|:----------
 `preKeyId`|Number|The identifier of the pre-key.
 
-#### getRemotePreKeyBundle
-
-```
-getRemotePreKeyBundle(remoteIdentity) → {PreKeyBundle}
-```
-
-Retrieve a pre-key bundle for a remote identity. This will likely be retrieved from a remote server. A `PreKeyBundle` is
-a JavaScript object with the following properties:
-
-Name|Type|Description
-:---|:---|:----------
-`identityKey`|ArrayBuffer|The remote identity's public key.
-`preKeyId`|Number|The identifier of the pre-key included in this bundle.
-`preKey`|ArrayBuffer|The public half of the pre-key.
-`signedPreKeyId`|Number|The identifier of the signed pre-key included in this bundle.
-`signedPreKey`|ArrayBuffer|The public half of the signed pre-key.
-`signedPreKeySignature`|ArrayBuffer|The signature associated with the `signedPreKey`.
-
 ##### Parameters
 
 Name|Type|Description
 :---|:---|:----------
 `remoteIdentity`|Identity|The identity of the remote entity. The type is the same as the type you pass to into
 the methods on Axolotl.
 
-#### isRemoteIdentityTrusted
-
-```
-isRemoteIdentityTrusted(remoteIdentity, identityPublicKey) → {Boolean}
-```
-
-Determine if the public key associated with the remote identity is trusted. It is up to the application to determine
-an appropriate algorithm for this.
-
-##### Parameters
-
-Name|Type|Description
-:---|:---|:----------
-`remoteIdentity`|Identity|The identity of the remote entity.
-`identityPublicKey`|ArrayBuffer|The purported remote identity's public key.
-
-#### hasSession
-
-```
-hasSession(identity) → {Boolean}
-```
-
-Determine if there is a stored session for the identity.
-
-##### Parameters
-
-Name|Type|Description
-:---|:---|:----------
-`identity`|Identity|The identity.
-
-#### getSession
-
-```
-getSession(identity) → {String}
-```
-
-Retrieve the session state associated with the identity.
-
-##### Parameters
-
-Name|Type|Description
-:---|:---|:----------
-`identity`|Identity|The identity.
-
-#### putSession
-
-```
-putSession(identity, sessionState) → {Void}
-```
-
-Store the session state along with the identity.
-
-##### Parameters
-
-Name|Type|Description
-:---|:---|:----------
-`identity`|Identity|The identity.
-`sessionState`|String|The serialised session state.
-
 ### Using Axolotl
 
 Start by instantiating Axolotl:
@@ -229,4 +152,4 @@ axol.decryptPreKeyWhisperMessage("alice", ciphertext).then(function(plaintext) {
 });
 ```
 
-and that's it!
+See [Axolotl.js](src/Axolotl.js) for more detailed API documentation.

bower.json

@@ -1,7 +1,7 @@
 {
   "name": "axolotl",
   "main": "dist/axolotl.js",
-  "version": "0.9.0",
+  "version": "1.0.0",
   "authors": [
     "Joe Bandenburg <joe@bandenburg.com>"
   ],

dist/axolotl.js

@@ -1,6 +1,6 @@
 {
   "name": "axolotl",
-  "version": "0.9.1",
+  "version": "1.0.0",
   "description": "A JavaScript port of libaxolotl. Axolotl is a ratcheting forward secrecy protocol.",
   "main": "dist/axolotl.js",
   "directories": {

package.json

@@ -16,10 +16,12 @@
  */
 
 import SessionFactory from "./SessionFactory";
+import SessionCipher from "./SessionCipher";
 import {InvalidMessageException} from "./Exceptions";
 import Store from "./Store";
 import Crypto from "./Crypto";
 import co from "co";
+import axolotlCrypto from "axolotl-crypto";
 
 /**
  * A public/private key pair
@@ -90,6 +92,7 @@ function Axolotl(crypto, store) {
     var wrappedCrypto = new Crypto(crypto);
 
     var sessionFactory = new SessionFactory(wrappedCrypto, wrappedStore);
+    var sessionCipher = new SessionCipher(wrappedCrypto);
 
     /**
      * Generate an identity key pair. Clients should only do this once, at install time.
@@ -176,67 +179,67 @@ function Axolotl(crypto, store) {
     });
 
     /**
-     * Encrypt a message using the session associated with toIdentity. If no such session exists, it will be created.
+     * @typedef {Object} PreKeyBundle
+     * @property {ArrayBuffer} identityKey - The remote identity's public key.
+     * @property {Number} preKeyId - The identifier of the pre-key included in this bundle.
+     * @property {ArrayBuffer} preKey - The public half of the pre-key.
+     * @property {Number} signedPreKeyId - The identifier of the signed pre-key included in this bundle.
+     * @property {ArrayBuffer} signedPreKey - The public half of the signed pre-key.
+     * @property {ArrayBuffer} signedPreKeySignature - The signature associated with the `signedPreKey`
+     */
+
+    /**
+     * Create a session from a pre-key bundle, probably retrieved from a server.
+     * @method
+     * @type {PreKeyBundle} a pre-key bundle
+     * @returns {Promise.<Session, Error>}
+     */
+    this.generateSignedPreKeyBundle = sessionFactory.createSessionFromPreKeyBundle;
+
+    /**
+     * Create a session from a PreKeyWhisperMessage.
+     * @method
+     * @type {Session} session - a session, if one exists, or null otherwise.
+     * @type {ArrayBuffer} preKeyWhisperMessageBytes - the bytes of a PreKeyWhisperMessage.
+     * @returns {Promise.<Session, Error>}
+     */
+    this.createSessionFromPreKeyWhisperMessage = sessionFactory.createSessionFromPreKeyWhisperMessage;
+
+    /**
+     * Encrypt a message using the session.
      * <p>
-     * It is safe to call this method multiple times without waiting for the returned promises to be resolved. In this
-     * case, operations may be queued to ensure sessions are in the correct state for each encryption.
+     * If this method succeeds, the passed in session should be destroyed. This method must never be called with
+     * that session again.
      *
      * @method
-     * @param {Identity} toIdentity - the identity of the intended recipient
-     * @param {ArrayBuffer} message - the message bytes to be encrypted
-     * @return {Promise.<ArrayBuffer, (InvalidKeyException|UntrustedIdentityException)>} encrypted message bytes if
-     * fulfilled. May be rejected if a fresh session is required and the pre key bundle returned from the server is
-     * invalid.
+     * @param {Session} session
+     * @param {ArrayBuffer} message - the message bytes to be encrypted (optionally padded)
+     * @return {Promise.<Object, Error>} an object containing the encrypted message bytes as well as a new session
      */
-    this.encryptMessage = co.wrap(function*(toIdentity, message) {
-        var session;
-        var hasSession = yield sessionFactory.hasSessionForIdentity(toIdentity);
-        if (hasSession) {
-            session = yield sessionFactory.getSessionForIdentity(toIdentity);
-        } else {
-            var preKeyBundle = yield wrappedStore.getRemotePreKeyBundle(toIdentity);
-            session = yield sessionFactory.createSessionFromPreKeyBundle(toIdentity, preKeyBundle);
-        }
-        return yield session.encryptMessage(message);
-    });
+    this.encryptMessage = sessionCipher.encryptMessage;
 
     /**
-     * Decrypt a WhisperMessage using the session associated with fromIdentity.
+     * Decrypt a WhisperMessage using session.
      * <p>
-     * It is safe to call this method multiple times without waiting for the returned promises to be resolved. In this
-     * case, operations may be queued to ensure sessions are in the correct state for each decryption.
+     * If this method succeeds, the passed in session should be destroyed. This method must never be called with
+     * that session again.
      *
      * @method
-     * @param {Identity} fromIdentity - the identity of the intended recipient
-     * @param {ArrayBuffer} message - the encrypted message bytes
-     * @return {Promise.<ArrayBuffer, (InvalidMessageException|DuplicateMessageException)>} decrypted message bytes if
-     * fulfilled. May be rejected if a session does not exist, the message is invalid or has been decrypted before.
+     * @param {Session} session
+     * @param {ArrayBuffer} whisperMessageBytes - the encrypted message bytes
+     * @returns {Promise.<Object, InvalidMessageException>} an object containing the decrypted message and a new session
      */
-    this.decryptWhisperMessage = co.wrap(function*(fromIdentity, message) {
-        var hasSession = yield sessionFactory.hasSessionForIdentity(fromIdentity);
-        if (!hasSession) {
-            throw new InvalidMessageException("No session for message");
-        }
-        var session = yield sessionFactory.getSessionForIdentity(fromIdentity);
-        return yield session.decryptWhisperMessage(message);
-    });
+    this.decryptWhisperMessage = sessionCipher.decryptWhisperMessage;
 
     /**
-     * Decrypt a PreKeyWhisperMessage using the session associated with fromIdentity.
-     * <p>
-     * It is safe to call this method multiple times without waiting for the returned promises to be resolved. In this
-     * case, operations may be queued to ensure sessions are in the correct state for each decryption.
+     * Unwrap the WhisperMessage from a PreKeyWhisperMessage and attempt to decrypt it using session.
      *
      * @method
-     * @param {Identity} fromIdentity - the identity of the intended recipient
-     * @param {ArrayBuffer} message - the encrypted message bytes
-     * @return {Promise.<ArrayBuffer, (InvalidMessageException|DuplicateMessageException)>} decrypted message bytes if
-     * fulfilled. May be rejected if the message is invalid or has been decrypted before.
+     * @param {Session} session
+     * @param {ArrayBuffer} preKeyWhisperMessageBytes - the encrypted message bytes
+     * @returns {Promise.<Object, InvalidMessageException>} an object containing the decrypted message and a new session
      */
-    this.decryptPreKeyWhisperMessage = co.wrap(function*(fromIdentity, message) {
-        var session = yield sessionFactory.createSessionFromPreKeyWhisperMessage(fromIdentity, message);
-        return yield session.decryptPreKeyWhisperMessage(message);
-    });
+    this.decryptPreKeyWhisperMessage = sessionCipher.decryptPreKeyWhisperMessage;
 
     Object.freeze(self);
 }

src/Axolotl.js

@@ -33,5 +33,5 @@ export default {
     // TODO: Make these configurable?
     maximumRetainedReceivedChainKeys: 5,
     maximumMissedMessages: 2000,
-    maximumSessionsPerIdentity: 40
+    maximumSessionStatesPerIdentity: 40
 };