Add README

README.md

@@ -1,3 +1,38 @@
-# multicrypt
+# Multicrypt - multi-key encryption
 
-Multicrypt is a library for multi-key reversible encryption.
+Multicrypt is a library for multi-key reversible encryption. That is, it provides a simple and secure interface for encrypting a payload such that it can be decrypted by any one of a number of keys, and the payload can be shared with new keys by users with existing keys.
+
+## How It Works
+
+Multicrypt uses an enveloped-data architecture whereby the payload is encrypted with a master key, and that master key is then encoded using each user's key.
+
+This allows any user to decode the master key and, consequently, the payload, without having to know the master key directly.
+
+The library is structured in such a way that discourages exposing the master key directly. In fact, your code should interact with the library, rather than the master key directly, which prevents exposing the master key at any point.
+
+## Getting Started
+
+Here's a quick overview of how to use Multicrypt:
+
+```ts
+import { SharedValue } from 'multicrypt'
+
+const value = 'value to be encrypted'
+const keyOne = 'some key'
+const keyTwo = 'some other key'
+
+// Encode a new shared value using keyOne
+const shared = await SharedValue.create<string>(keyOne, value)
+
+// Allow keyTwo to access the shared value:
+await shared.addKey(keyOne, keyTwo)
+
+// Get the shared value:
+const decodedValue = await shared.get(keyTwo)  // => 'value to be encoded'
+
+// Set the shared value:
+const encodedValue = await shared.set(keyTwo, 'override string')
+
+// Serialize the shared value securely:
+const serialized = shared.toJSON()
+```