docs: initial set of docs
Change-Id: Icb0269498bf2eedebc929f1ec5738cdb4eb1df52
diff --git a/community/coding-guidelines.md b/community/coding-guidelines.md
new file mode 100644
index 0000000..b644394
--- /dev/null
+++ b/community/coding-guidelines.md
@@ -0,0 +1,123 @@
+# Coding Guidelines
+
+## Code organization
+
+Vanadium is spread across multiple [git repositories]. The [contributor
+installation] process arranges these repositories as follows:
+
+```
+ $V23_ROOT
+ devtools # Contributor tools
+ environment # Platform dependent configuration
+ .manifest # Multi-repo control data
+ release # Source code
+ go/src/v.io/v23 # Interfaces
+ go/src/v.io/x # Implementation
+ devtools # Contributor tool source
+ lib # Developer libs
+ ref # Reference implementation of v23
+ javascript # JS compatibility
+ projects # Example apps
+ playground # Write/build/run v23 code on web
+ browser # Vanadium namespace browser
+ chat # Chat program
+ scripts # Contributor scripts
+ third_party # Third party code
+ www # Source for this site
+```
+
+Each repository has a `README` file summarizing its purpose. The `devtools`
+directory isn't a repository, but rather a top level directory where
+contributor tools are placed during installation. The `.manifest` repository
+contains the configuration that describes this repository arrangement.
+
+Things move around, so its best to examine your local installation for
+the latest arrangement.
+
+ <!--
+ Suggestions for how to name things (hyphens vs underscores).
+ Using optional arguments - variadics/varargs vs Options objects.
+ -->
+
+## Go
+
+Use [gofmt] and suggestions from [Effective Go].
+
+### Interfaces
+
+Vanadium interfaces are defined in the [`go/src/v.io/v23`][v23 code]
+tree in files named `model.go`. For example, the file
+[`security/model.go`][security model] holds security interface
+definitions.
+
+### Testing
+
+A test for package `foo` should be in package `foo_test`. This way, tests can
+depend on anything they like without introducing cycles or affecting non-test
+binaries.
+
+If a test must touch the internals of some package `foo`, that test can be in
+package `foo`, but must keep its dependencies to a minimum, and must have a name
+that ends with `_internal_test.go`.
+
+Most tests should import the [`v.io/x/ref/test` package][test package]
+and invoke its [`Init` function][test init] in order to configure
+logging, random number generators etc. Doing so will assist in
+debugging failing tests. For example:
+
+ * The `-vv` and `-vmodule` flags can be used to control logging verbosity
+ * The seed of the random number generator is logged when running tests. This
+ is useful when trying to reproduce failures that may not occur when the
+ random number generator is seeded differently.
+
+ <!-- explain modules, expect, timekeeper? -->
+ <!--
+ Describe dependency management (apis vs. impls,
+ what can depend on what).
+ -->
+
+## VDL
+
+The `devtools/bin/vdl` tool uses VDL files to generate files
+containing [RPC] stub code for various languages - Go, JavaScript,
+etc.
+
+[VDL] is not Go, but is modeled after Go, so VDL code should follow
+Go's style guidelines.
+
+VDL files have a [Go-like notion of packages][packages]. Go code
+generated from a VDL file must appear in a location that respects both
+the VDL file's package name and the value of `GOPATH`. In a Go-based
+project like Vanadium, the simplest way to accomplish this is to place
+VDL source files into the `go/src` tree at the location that the
+generated Go should be placed.
+
+## JavaScript
+
+Follow the [Node.js Style Guide]. Use our [.jshintrc].
+
+ <!-- Documentation generation - jsdoc -->
+
+## Shell
+
+We prefer Go programs over shell scripts for jobs traditionally given
+to shell scripts.
+
+If you must write a shell script, follow the
+[Google Shell Style Guide].
+
+[.jshintrc]: https://github.com/vanadium/js/blob/master/.jshintrc
+[Effective Go]: http://golang.org/doc/effective_go.html
+[Google Shell Style Guide]: https://google-styleguide.googlecode.com/svn/trunk/shell.xml
+[Node.js Style Guide]: https://github.com/felixge/node-style-guide
+[RPC]: ../glossary.md#remote-procedure-call-rpc-
+[VDL]: ../glossary.md#vandium-definition-language-vdl-
+[brad talk]: http://talks.golang.org/2014/gocon-tokyo.slide#36
+[contributor installation]: contributing.md#repositories
+[git repositories]: https://github.com/vanadium
+[gofmt]: https://golang.org/cmd/gofmt/
+[packages]: https://golang.org/doc/code.html#PackagePaths
+[v23 code]: https://github.com/vanadium/go.v23
+[security model]: https://github.com/vanadium/go.v23/blob/master/security/model.go
+[test package]: https://github.com/vanadium/go.ref/tree/master/test
+[test init]: https://github.com/vanadium/go.ref/blob/master/test/init.go
diff --git a/community/contributing.md b/community/contributing.md
new file mode 100644
index 0000000..0f86512
--- /dev/null
+++ b/community/contributing.md
@@ -0,0 +1,330 @@
+# Contributing
+
+## Reporting issues
+
+We use GitHub for tracking Vanadium issues:
+https://github.com/vanadium/issues/issues
+
+## Developer setup
+
+### Contributor license agreement
+
+Before patches can be accepted, contributors must sign the Google Individual
+[Contributor License Agreement][cla] (CLA), which can be done online. The CLA
+is necessary since contributors own the copyright to their code, even after it
+becomes part of the codebase, so permission is required to use and distribute
+that code. Contributors don't have to sign the CLA until after a patch has
+been submitted for review and a member has approved it, but the CLA must be
+signed before the patch is committed into the codebase.
+
+Before starting work on a large contribution, we recommend that you get in
+touch through the [issue tracker] with your idea so that other contributors
+and authors can help out and possibly guide you.
+
+Contributions made by corporations are covered by a different agreement than
+the one above, the [Software Grant and Corporate Contributor License Agreement][corp-cla].
+
+### Credentials
+
+As a new developer you need to gain access to vanadium.googlesource.com
+and request a password for accessing it as follows:
+
+1. Go to https://vanadium.googlesource.com, log in with your identity, click
+on "Generate Password", and follow the instructions to store the
+credentials for accessing vanadium.googlesource.com locally.
+
+2. Go to https://vanadium-review.googlesource.com and log in with your
+identity. This will create an account for you in the code review system.
+
+## Machine setup
+
+Make sure your machine has the credentials as described above.
+
+### Prerequisites
+
+If you are developing on Darwin (OS X), you need to have the Xcode command
+line tools installed. You can quickly install these in the terminal with:
+
+
+ # Mac only prerequisite install
+ xcode-select --install
+
+The instructions on this page assume that the following software is installed and in your `PATH`:
+
+* curl
+* [git]
+* [Go version 1.5 or newer][go-install]
+
+### Repositories
+
+To contribute to Vanadium, you will want to setup up a directory which
+contains the entire collection of repositories (projects) which make up the
+Vanadium universe of language libraries, command line tools, services,
+website, example projects, and development tools like [v23].
+
+#### V23_ROOT environment variable
+
+Set the `V23_ROOT` environment variable. Use an absolute path that points to a local file system location (remote file system such as NFS are discouraged for performance reasons and to avoid ENOKEY 'git' errors). **Use a directory that does NOT exist**; the following steps will create it.
+
+```bash
+# Edit to taste
+export V23_ROOT=${HOME}/vanadium
+```
+
+Be sure to add the `$V23_ROOT` environment variable to your profile.
+
+#### Setup script
+
+Run the initial setup script (this might take several minutes):
+
+```bash
+curl -u vanadium:D6HT]P,LrJ7e https://v.io/bootstrap | bash
+```
+
+#### Update your PATH
+
+Add `$V23_ROOT/devtools/bin` to your `PATH`.
+
+```bash
+export PATH=$PATH:$V23_ROOT/devtools/bin
+```
+
+Be sure to add the modified `$PATH` to your profile.
+
+#### REQUIRED: profile installation
+
+Extra development profiles such as ARM cross-compilation, support for mobile, or web development can be installer using the `v23` command. To see a list of available profiles run:
+
+```bash
+v23 profile list
+```
+
+Profiles can be installed with `v23 profile install <profile>` where `<profile>` is replaced with one of the items from the list.
+
+Invocations of the `v23 profile install` command are idempotent.
+
+##### syncbase profile
+
+In order to successfully install/build the Vanadium Go code you will need to install syncbase dependencies with:
+
+```bash
+v23 profile install syncbase
+```
+
+**The syncbase profile is required.**
+
+##### Node.js profile
+
+**OS X only:** If you are on Darwin (OS X) be sure to have a full Xcode install via the App Store (not just the command line tools).
+
+In order to install the nodejs profile run:
+
+```bash
+v23 profile install nodejs
+```
+
+## Development
+
+### Building and testing
+
+#### Go
+
+To compile vanadium go codebase, use the following commands:
+
+```bash
+# For the host OS and architecture
+v23 go <command> <packages>
+
+# For cross-compilation using default toolchain
+GOARCH=<arch> GOOS=<os> v23 go <command> <packages>
+
+# For cross-compilation using development profiles
+V23_PROFILE=<profile> v23 go <command> <packages>
+```
+
+These commands setup the `GOPATH` and other environment variables so the
+Vanadium libraries and binaries are built for the desired architecture.
+
+##### Examples
+
+Check that the Go code builds
+
+```bash
+v23 go build v.io/...
+```
+
+Run all Go tests
+
+```bash
+v23 go test v.io/...
+```
+
+Install all the Go binaries
+
+```bash
+v23 go install v.io/...
+```
+
+#### JavaScript
+
+Ensure that you have the required profile set up by running:
+
+ v23 profile install nacl nodejs
+
+This will install dependencies needed to build and run the Vanadium JavaScript
+projects and the [Vanadium Chrome extension]. Darwin (OS X) users should be sure
+to have a full install of Xcode.
+
+##### Dependencies
+
+To build and test Vanadium JavaScript library, please ensure Vanadium Go
+binaries are installed first (they are required for integration
+testing).
+
+Build the Go Vanadium binaries.
+
+```bash
+v23 go install v.io/...
+```
+
+All other dependencies can be satisfied via the default `make` target.
+
+```bash
+cd $V23_ROOT/release/javascript/core
+make
+```
+
+##### Testing
+
+Build and test the JavaScript API.
+
+ make test
+
+Remove all JavaScript build artifacts
+
+ make clean
+
+### Git workflow
+
+All of the individual Vanadium projects use `git` for version control. The
+"master" branch of each local repository is reserved for tracking the remote
+https://vanadium.googlesource.com counterpart. All Vanadium development should
+take place on a non-master (feature) branch. Once your code has been reviewed
+and approved, it will be merged into the remote master via our code review system and brought to your local instance via `v23 update`.
+
+**The only way to contribute to master is via the Gerrit code review process.**
+
+To submit a change for review you will need to squash your feature branch into a single commit and send the patch to Gerrit for review. The command `v23 cl` simplifies this process and is described in greater detail below.
+
+#### Creating a change
+
+1. Sync the master branch to the latest version of the project:
+
+ v23 update
+
+2. Create a new branch for your change
+
+ # replacing `<branch>` with your branch name
+ v23 cl new <branch>
+
+3. Make modifications to the project source code.
+4. Stage any changed files for a commit:
+
+ git add <file1> <file2> ... <fileN>
+
+5. Commit your modifications:
+
+ git commit
+
+6. Repeat steps 3-5 as necessary.
+
+#### Syncing a change to the latest version of the project
+
+1. Update all of the local master branches using the `v23` command:
+
+ v23 update
+
+2. If you are not already on it, switch to the feature branch that corresponds
+to the change you are trying to bring up to date with the upstream:
+
+ git checkout <branch>
+ git merge master
+
+3. If there are no conflicts, you are done.
+4. If there are conflicts:
+ * Manually resolve the conflicted files.
+ * Stage the resolved files for a commit with `git add <pathspec>...`
+ * Commit the resolved files with `git commit`
+
+#### Requesting a review
+
+1. Switch to the branch that corresponds to the change in question.
+
+ git checkout <branch>
+
+2. Submit your change to Gerrit with the `v23 cl` command.
+
+ # <reviewers> is a comma-seperated list of emails or LDAPs
+ # Alternatively reviewers can be added via the Gerrit UI
+ v23 cl mail -r=<reviewers>
+
+If you are unsure who to add as a reviewer you can leave off the `-r` flag. Our team periodically scans for CLs and a reviewer will come along. If you would rather not wait, feel free to let us know about your change by filing an issue on GitHub.
+
+#### Reviewing a change
+
+1. Follow the link you received in an email notifying you about a
+ review request.
+2. Add comments as you see fit.
+3. When you are finished, click on the "Reply" button to submit your
+ comments, selecting the appropriate score.
+
+#### Addressing review comments
+
+1. Switch to the branch that corresponds to the change in question
+
+ git checkout <branch>
+
+2. Modify and commit code as as described [above](#creating-a-change).
+3. Be sure to address each review comment on Gerrit.
+4. Once you have addressed all review comments be sure to reply at the
+ top of the Gerrit UI for the specific patch.
+5. Once you have addressed all review comments, you can update the change with
+ a new patch using:
+
+ v23 cl mail
+
+#### Submitting a change
+
+1. Work with your reviewers to receive "+2" score. If your change no longer
+ applies cleanly due to upstream changes, the reviewer may ask you to rebase
+ it. You will need to follow the steps in the section above: ["Syncing a
+ change to the latest version of the
+ project"](#syncing-a-change-to-the-latest-version-of-the-project) and then
+ run `v23 cl mail` again
+2. The reviewer will submit your change and it will be merged into the master
+ branch.
+3. Optional: Delete the feature branch once it has been submitted:
+
+ git checkout master
+ v23 cl cleanup <branch>
+
+#### Useful shortcuts
+
+There are several useful shorcuts you can use for quick access to changes and
+issues.
+
+* [v.io/issues](https://v.io/issues): Takes you to the issues list.
+* v.io/i/[num]: Takes you to a specific issue.
+* [v.io/i/new](https://v.io/i/new): Creates a new issue.
+* [v.io/review](https://v.io/review): Takes you to your review dashboard.
+* v.io/c/[num]: Takes you to the review for a specific change.
+
+[git]: http://git-scm.com/
+[go-install]: http://golang.org/doc/install
+[brew]: http://brew.sh/
+[gerrit]: https://vanadium-review.googlesource.com
+[Vanadium Chrome extension]: ../tools/vanadium-chrome-extension.md
+[v23]: ../tools/v23.md
+[cla]: https://cla.developers.google.com/about/google-individual?csw=1
+[corp-cla]: https://cla.developers.google.com/about/google-corporate?csw=1
+[issue tracker]: https://github.com/vanadium/issues/issues
diff --git a/concepts/device-management.md b/concepts/device-management.md
new file mode 100644
index 0000000..988ad31
--- /dev/null
+++ b/concepts/device-management.md
@@ -0,0 +1,112 @@
+# Device Management
+
+Vanadium targets a broad range of compute devices and environments. Vanadium's device management system securely integrates physical devices and software applications available in the system.
+
+## Devices and applications
+
+A __device__ abstracts a system running Vanadium software, although the device need not be exclusively for Vanadium apps - for example, the system could be running natively installed applications alongside Vanadium applications. Typically, a device is a physical computing device, but a device could also be a virtual machine or a browser environment.
+
+An __application__ is a piece of software built using Vanadium. We use "app" as shorthand for "application", without adopting any of the specific meanings the term "app" may have elsewhere (e.g. in the context of mobile device app stores). Vanadium applications instantiate the Vanadium runtime. Usually, a running instance of a binary corresponds to an application, though applications can be multi-processed, or can be scripts (such as JavaScript applications), or can be [Docker][docker] images.
+
+Applications are described by an __application envelope__. The envelope
+contains information needed by the device to install and run the application,
+like the application title, location of its binary or script, and configuration settings.
+
+Devices, as environments for apps, are characterized by their ability to build, install, and run apps. Except in tightly controlled organizations, the landscape of devices is typically diverse. Vanadium introduces the concept of a __profile__ in order to prevent application publishers and device administrators from having to contend with myriad possible device setups.
+
+A profile abstracts the characteristics of a physical device, its operating system, and available libraries. It is essentially a label for a particular configurations of devices, though the level of specificity will depend on the profile author. For example, a label could be as generic as `android` or as specific as `raspberry-ubuntu-14.04-media`. A device with a given profile is expected to be able to install and run applications built for that profile, and heterogeneous devices should be able to usefully support the same profile. Profiles may also be used to match configuration requirements and parameters, security policies or any piece of management information that may need to vary based on the type and configuration of a given device.
+
+A device can be assigned a profile manually, or it can programmatically deduce the set of profiles with which it is compatible. If no known profile matches the device, the device is automatically given a profile that is unique to it.
+
+Devices are matched with apps by an __application repository service__. The matching is based on profiles: the device presents the service with the profiles it supports, and the service returns the envelope for the application that matches at least one of the profiles presented.
+
+Matching apps with devices based on profiles is also how our build system ensures that it provides test coverage without having to support all possible machine configurations. Devices that test a given app can report back with a test status for the profile they support.
+
+Application binaries, scripts, docker images, or related data resources (e.g. images, style sheets) are stored in a __binary repository service__. The binary service allows uploading and downloading arbitrary binary blobs identified by their object name.
+
+## Device manager service
+
+Vanadium provides remote management APIs to manage devices and apps.
+
+Each device runs the Vanadium __device manager service__. The device manager
+allows RPCs to control the device's state and security properties (such as
+ownership and access privileges). The device manager also manages applications
+running on the device.
+
+An __application installation__ is an object corresponding to an application
+envelope that was downloaded and installed by the device. A device can have several
+installations of the same application at any point in time (perhaps at different
+versions of the application). Each running instance of an application
+installation is represented by an __application instance__ object. There can be
+zero or more instances for every application installation. Each application
+instance is provided with its own private local storage.
+
+Each application installation and each application instance is identified by an
+object name implementing the __application service__. This allows operations
+such as installation/uninstallation of applications,
+starting/stopping/restarting of instances, updating application versions, and
+suspension/resumption of execution:
+
+ * `Install`/`Uninstall`: install a new application or uninstall the
+ application installation.
+ * `Instantiate`/`Delete`: create or destroy an instance of an application. Resources such as per-instance storage are allocated upon instantiation and reclaimed upon deletion.
+ * `Run`/`Kill`: start or stop the execution of an application instance. Per-instance
+ storage persists between runs of the instance.
+
+The __object naming scheme__ is as follows:
+ * `<device name>/device`: device manager service for device
+ * `<device name>/apps/<app title>/<installation id>`: application service for
+ installed application
+ * `<device name>/apps/<app title>/<installation id>/<instance id>`: application
+ service for an instance of the installed application
+
+For example,
+ * `<device name>/apps/google maps/0.Uninstall()`: uninstalls installation 0
+ of the Google Maps app
+ * `<device name>/apps/google maps/0/5.Kill()`: stops running instance 5 of
+ installation 0 of the Google Maps app
+
+Globbing at any level of the name hierarchy reveals the appropriate subtree of
+application installations and instances.
+
+Each application exposes the __app cycle manager service__ in addition to any
+other methods that the application may chose to expose. The app cycle manager
+service allows the device manager process to communicate with each app it runs
+for operations such as cleanly shutting down the app.
+
+## Security and identities
+
+The __security model__ revolves around which principals are allowed to perform
+which management operations, and around what capabilities an app is given on a
+device (see [Security Concepts][vanadium-security] for an overview of
+security primitives).
+
+### Device and application identities
+
+Each device is owned by the identity of the principal who claims it. All
+permissions are initially restricted to the owner, who may update the
+permissions on the administrative and operational methods as needed.
+Management methods for an application installation or instance are initially
+restricted to the same principal that installed or started it, and to the
+administrator(s) of the device.
+
+When a client asks the device manager to start an application instance, the
+client principal must provide the application instance with a blessing which
+becomes the default blessing for the principal of the application instance.
+
+### Application permissions
+
+Applications come signed by a publisher's identity which is verified by the
+device before installing the application.
+
+In the future, it will be possible to give applications permission on the
+device according to the device owner's trust relation with the publisher. For
+example, the owner may trust applications published by "Google Inc." with all
+capabilities, whereas she may trust applications published by "XYZ Games
+Corp." with access only to the screen and speakers. An application can request
+further capabilities as needed when it's running. On receiving requests, the
+user may allow or disallow based on their personal comfort level and/or on the
+perceived value of the app feature requesting the new capability.
+
+[docker]: https://www.docker.com/
+[vanadium-security]: security.md
diff --git a/concepts/naming.md b/concepts/naming.md
new file mode 100644
index 0000000..6bfeca9
--- /dev/null
+++ b/concepts/naming.md
@@ -0,0 +1,148 @@
+# Naming
+
+<!-- TODO(sadovsky): Fix embedded img tags. -->
+
+The Vanadium naming system enables discovery of devices, regardless of their
+physical locations - with or without an internet connection.
+
+## Object names
+
+Vanadium names, usually abbreviated to "_names_" refer to objects.
+
+Objects implement RPC methods. In other words, methods are invoked on
+object names. The basic primitive is thus:
+
+ name.method(args) -> results
+
+For example, if the name `/host:8080/a/y/foo.jpg` represents a JPEG file, then
+`/host:8080/a/y/foo.jpg.Get()` will return the contents of that file.
+
+Object names are hierarchical consisting of components separated by slashes (/).
+Glob patterns, as on Unix, are restricted to matching name components.
+
+Object names are resolved to obtain an _object address_. The underlying RPC
+protocol uses object addresses to establish communication with the process
+containing the named object prior to invoking methods on the object. The service
+that implements name resolution consists of servers, called _mount tables_, and
+a client library called the _namespace_ library.
+
+## Mount tables and namespaces
+
+Mount tables are similar to [DNS][DNS] servers and the namespace library to the
+DNS resolver. Similar to DNS and the [Unix filesystem][Unix filesystem], mount
+tables may be arranged in layered hierarchies. The resolution process
+implemented by the namespace library may iteratively communicate with multiple
+mount tables to resolve a single name. This is illustrated in the diagram
+below, which shows 6 mount tables. `ns1.v.io:8101` is the _root_ and
+`mount table a`, `mount table b` and `mount table c` are _mounted_ in it as `a`,
+`b`, `c`. Similarly, `mount table y` and `mount table z` are mounted in
+`mount table a` as `y` and `z`. To resolve the name `a/y`, the mount tables on
+`ns1.v.io:8101` and `mount table a` must be consulted. To resolve the name
+`a/y/foo/bar`, `mount table a/y` must also be consulted, since it serves
+mounts made below `y`.
+
+
+
+The first element of a name that begins with `/` points to the mount table at
+which to begin the resolution. For example, the name `/ns1.v.io:8101/a` starts
+resolution with the mount table `ns1.v.io:8101`. These names are called _rooted_
+because they need no additional state to perform the resolution, they stand by
+themselves.
+
+Names that don't begin with a `/` begin the resolution at a default (or
+current) mount table set in the process' namespace library. We
+call those names _relative_ because they need the state of the namespace
+library to determine how they are resolved.
+
+This is illustrated below, where process `Client 1` has a namespace
+that is relative to `ns1.v.io:8101`, its root, and hence can resolve
+`a`, `b`, `c`, `a/y`, and `a/z`.
+
+
+
+In contrast, process `Client 2` with `ns2.v.io:8102` as its root can
+resolve only `y` and `z`.
+
+
+
+The advantage of using a relative namespace is that it can define a context.
+For example, for debugging or testing one would set up the namespace to
+contain the emulated environment. It is similarly possible to provide context
+of nearby devices, or one local to a single machine.
+
+Rooted names can be used to specify an arbitrary server where name resolution
+will begin, thus overriding the root of the namespace asked to perform the
+resolution. This would allow `Client 2` to refer to `a` as `/ns1.v.io:8101/a`.
+The element immediately after the leading slash must be an address, either in
+`dnsname:port`, `ipv6:port`, or `ipv4:port` format, or in the Vanadium
+[endpoint format][endpoint] that encodes more detailed information about the
+server supporting the object (such as protocol versions or a globally unique
+id). In all cases they provide a starting point in the [forest][forest] of
+namespaces. The object addressed by that element can be another mount table or
+the terminal server.
+
+In essence, both rooted and relative names are the same. They represent a walk
+through a namespace that consists of a [directed cyclic graph][DCG] of mount
+tables ending in a server of the object we're trying to get at. The only
+difference with relative names is that we're assuming a "current directory" to
+start from as opposed to providing it in the name.
+
+
+
+User-supplied server code that implements RPCs also appears as names in mount
+tables. In the diagram above `Server 1` and `Server 2` provide a server called
+`srv` that can be accessed as `/ns1.v.io:8101/srv`, which will
+resolve to the server hosted by `Server 1` and `/ns1.v.io:8101/a/srv`,
+which will resolve to the server hosted by `Server 2`. The mount table at
+`ns1.v.io:8101` contains the entry for `Server 1` (as `srv`) and the
+mount table at `mount table a` contains the entry for
+`Server 2` (also called `srv`). Invoking `/ns1.v.io:8101/srv.Get()`
+will result in `Server 1` serving that method, whereas
+`/ns1.v.io:8101/a/srv.Get()` will be served by `Server 2`.
+
+The name resolution process is iterative. For `Client 1` to resolve `a/y/bar`,
+it will first ask `ns1.v.io:8101` to resolve `a/y/bar`, root
+will reply with `mount table a`'s address and `y/bar` as the "unresolved"
+portion of the name. `Client 1` will then ask `mount table a` to resolve
+`y/bar`, and so on.
+
+If the resolution reaches a leaf server (i.e. one that isn't
+a mount table such as `Serve 1` or `Server 2`) and there
+are still remaining components to the name, those
+"unresolved" components will be passed to the leaf server along with the operation.
+Thus the call `/ns1.v.io:8101/srv/foo/bar.Get()` will result in `Server 1` receiving
+the RPC `foo/bar.Get()`.
+
+It is possible to create cycles
+by creating mount tables that mount themselves through other mount tables. Cycles are
+handled by limiting the number of iterations the resolution algorithm will
+execute. That is, regardless of whether cycles are present, the
+resolution algorithm will bound the number of iterations it executes.
+
+## Mount entries
+
+Our examples above have shown mount tables pointing to other mount tables or to
+leaf servers but we haven't said what those pointers are. They are a set of
+equivalent _rooted_ names. They either specify different addresses for the same
+server reachable via different networks (for example IP, IPv6, and Bluetooth),
+or they specify addresses for servers that are themselves equivalent either
+because they are stateless or because they transparently synchronize their
+state. Thus, we can send an RPC to whichever one is available and that we can
+reach.
+
+Normally these rooted names point to the root of the server's namespace and that
+is what we have shown in our examples. However, you can also mount objects
+further inside the server's namespace. In the example above, we could have
+mounted `Server 1`s `/foo/bar` onto the name `/ns1.v.io:8101/quux`. In that
+case both `/ns1.v.io:8101/srv/foo/bar` and `/ns1.v.io:8101/quux` would resolve
+to the same object. You can use this to create aliases or nicknames for objects,
+or to create namespaces that represent some context (like all left handed green
+eyed poker players) without creating a specific server to provice such a
+grouping.
+
+[DCG]: http://en.wikipedia.org/wiki/Cycle_graph#Directed_cycle_graph
+[DNS]: http://en.wikipedia.org/wiki/Domain_Name_System
+[forest]: http://en.wikipedia.org/wiki/Forest_(graph_theory)#forest
+[Unix Filesystem]: http://en.wikipedia.org/wiki/Unix_File_System
+[endpoint]: ../glossary.md#endpoint
diff --git a/concepts/rpc.md b/concepts/rpc.md
new file mode 100644
index 0000000..c0625df
--- /dev/null
+++ b/concepts/rpc.md
@@ -0,0 +1,119 @@
+# RPC System
+
+The Vanadium remote procedure call ([RPC]) system enables [communication]
+between processes by presenting an API based on local function calls. Function
+calls are a familiar model to developers, and the API hides low-level details
+like the underlying network transport and data serialization protocols.
+
+## Basics
+
+There are two participants in RPC-based communication. The caller of an RPC is
+known as the **client** and the receiver that implements the RPC is known as the
+**server**. A single device may often behave as a client for some operations,
+and as a server for other operations.
+
+An example of a simple RPC:
+```
+ Divide(x, y int32) (quotient, remainder int32 | error)
+```
+
+The client calls `Divide` like a regular function, providing two integer input
+arguments `x` and `y`. The server implements `Divide` and returns either the
+result of `x/y` as two integer output arguments `quotient` and `remainder`, or
+an error. Notice that errors may always occur, e.g. the client may be unable to
+contact the server if the server isn't running. Every RPC includes the
+possibility of returning an error rather than the specified output arguments.
+
+An example of a streaming RPC:
+```
+ Print(format string) stream<int32, string> (string | error)
+```
+
+The client calls `Print` and provides a single string argument `format`.
+Thereafter the client may stream zero or more integer arguments to the server,
+and the server will reply with the string representation of that argument. When
+the operation is finished, the server responds with a string containing any
+final output. The input and output arguments behave identically to the
+non-streaming example.
+
+The streaming arguments are transferred after the input arguments are sent from
+client to server, and before the output arguments are sent from server to
+client. The exact protocol for the streaming arguments is determined by the
+application; supported modes include client to server streaming for uploads,
+server to client streaming for downloads, as well as bi-directional streaming
+for other use cases.
+
+The RPC system takes care of the underlying protocols necessary for all of these
+forms of communication.
+
+## VDL
+
+The Vanadium Definition Language (VDL) enables interoperability between
+software components executing in different computing environments. For
+example, a frontend written in JavaScript running on a mobile phone may wish
+to communicate with a backend written in Go running in the cloud.
+
+VDL has a well-defined type system and semantics that specify the baseline
+behavior for all RPCs. Each native computing environment or programming
+language has a mapping between native concepts and VDL. Specifying application
+level RPC protocols in terms of VDL enables clients and servers to be easily
+written for any supported environment.
+
+VDL can define four different entities:
+
+**Interfaces** contain methods that can be invoked via RPCs.
+```
+// Restaurant contains methods to order items of food,
+// and to check their price without ordering.
+type Restaurant interface {
+ // Order orders the item of food, and returns its price.
+ Order(item Food) (Price | error)
+ // Price returns the price for the item of food.
+ Price(item Food) (Price | error)
+}
+```
+**Types** define data sent via RPC.
+```
+// Food enumerates the available food items.
+type Food enum {
+ Pizza
+ Pasta
+ Calzone
+}
+// Price represents the price of a food item.
+type Price uint16
+```
+**Constants** to hold fixed data used by the application protocol.
+```
+// StandardPrices holds standard fixed prices for each
+// food item.
+const StandardPrices map[Food]Price{
+ Pizza: 10, Pasta: 8, Calzone: 9,
+}
+```
+**Errors** that may be returned from failing RPCs, with support for
+internationalization of the error messages.
+```
+// MissingIngredients is returned when a food item is
+// unavailable, because an ingredient is out of stock.
+error MissingIngredients(ingredientName string) {
+ "en" : "{ingredientName} is out of stock"
+}
+```
+
+For more details see the [VDL specification].
+
+## VOM
+
+The Vanadium Object Marshalling (VOM) format is the underlying serialization
+format used by the RPC system. VOM supports serialization of all types
+representable in VDL. It is a self-describing protocol that retains full type
+information when transmitting values and, in particular, retains type
+information for all method arguments.
+
+For more details see the [VOM specification].
+
+[RPC]: http://en.wikipedia.org/wiki/Remote_procedure_call
+[communication]: http://en.wikipedia.org/wiki/Inter-process_communication
+[VDL specification]: ../designdocs/vdl-spec.md
+[VOM specification]: ../designdocs/vom-spec.md
diff --git a/concepts/security.md b/concepts/security.md
new file mode 100644
index 0000000..300ca0d
--- /dev/null
+++ b/concepts/security.md
@@ -0,0 +1,362 @@
+# Security
+
+The Vanadium security model defines mechanisms for identification,
+authentication, and authorization. The model supports fully decentralized,
+fine-grained, and auditable delegation of authority.
+
+For example, Alice could choose to delegate access to Bob only
+under the following conditions:
+* the operation is <code>Read</code>, and
+* the current time is between <code>6PM and 8PM</code>, and
+* Bob is in Alice's <code>"friends"</code> group, and
+* Bob is in close physical proximity of Alice
+
+Such delegations do not have to go through the cloud or any centralized
+service, can be accomplished by a single interaction between Alice and Bob,
+and encode an audit trail of the principals involved in the delegation.
+
+All network communication is always mutually authenticated and
+encrypted. The model is heavily influenced by the work on [Simple
+Distributed Security Infrastructure] by Ronald Rivest and Butler Lampson.
+
+## Principals & blessings
+
+The security model is centered around the concepts of _principals_ and
+_blessings_. A _principal_ in the Vanadium framework is a public and
+private [key pair]. All Vanadium processes act on behalf of a principal.
+The notation (<code>P<sub>Alice</sub>, S<sub>Alice</sub></code>) is used
+to refer to the public and private key respectively of a principal Alice.
+
+Principals have a set of human-readable names bound to them, via _blessings_.
+For instance, a television principal, represented by the key pair
+(<code>P<sub>tv</sub>, S<sub>tv</sub></code>), may have a blessing from the
+manufacturer with the human-readable name of `popularcorp/products/tv`.
+Principals can have multiple blessings bound to them and thus have multiple
+names, each reflecting the principal that granted the blessing. For example,
+the particular PopularCorp tv owned by Alice might also have the name
+`alice/devices/hometv`.
+
+Principals are authenticated and authorized based on the blessing names bound to them.
+For example, a service may grant access to `alice/devices/hometv`, which means that all
+principals with a blessing name matching `alice/devices/hometv` will have access.
+Service administrators always use blessing names, not public keys, when making
+authorization decisions or inspecting audit trails.
+
+Concretely, blessings are represented by [public-key certificate] chains bound to the
+principal's public key. For example, the name
+`popularcorp/products/tv` could be bound to the public key
+<code>P<sub>tv</sub></code> using a chain of three certificates:
+
+1. Certificate with public key <code>P<sub>popularcorp</sub></code> and name
+`popularcorp`, _chained to_
+2. Certificate with public key <code>P<sub>products</sub></code> and name `products`, _chained to_
+3. Certificate with public key <code>P<sub>tv</sub></code> and name `tv`
+
+Chaining means that the certificate is signed by the private counterpart of the
+public key in the previous certificate. The first certificate in the chain
+is self-signed, i.e. signed by private counterpart of the public key mentioned
+in the certificate (<code>P<sub>popularcorp</sub></code> in this case).
+
+The first certificate is also called the _root certificate_ and the first
+certificate's public key is called the _blessing root_.
+
+The term _blessing_ is used to refer to a certificate chain and the term
+_blessing name_ is used to refer to the human-readable name specified in the
+certificate chain. If it is clear from the context, then _blessing_ may be
+used in lieu of _blessing name_ for brevity.
+
+The private key of the principal will generally be hosted by a [TPM] (Trusted
+Platform Module) or an agent process and will not be held in memory of the
+application process to protect against leakage. Private keys are never sent on
+the network and are used only for digital signing operations.
+
+## Mutual authentication
+
+Clients and servers in a Vanadium remote procedure call (RPC) always act on
+behalf of a principal, and mutually authenticate each other via blessings bound
+to the other end's principal. The [Vanadium authentication protocol] allows
+clients and servers to exchange blessings bound to them, and verify that the
+other end possesses the private counterpart of the public key to which their
+blessings are bound. At the end of the protocol, an encrypted channel is
+established between the client and server for performing the RPC.
+[Forward-secrecy] safe protocols (like [TLS] with [ECDHE] key exchanges or a
+[NaCl box] with ephemerel keys) are used for setting up the encrypted channel.
+
+## Delegation
+
+The authorizations associated with a principal are determined solely by the
+blessings bound to the principal. Delegation of authority across principals is
+achieved via the _Bless_ operation. Bless allows a principal to extend one
+of its blessings and create a blessing bound to another principal's public key,
+thereby delegating any authorizations associated with the blessing.
+
+For example, a principal (<code>P<sub>alice</sub>, S<sub>alice</sub></code>) may bless another principal
+(<code>P<sub>tv</sub>, S<sub>tv</sub></code>) by extending one of
+her blessings, say `alice`, with a certificate with the name `devices/hometv` and the tv's public key
+<code>P<sub>tv</sub></code>. This certificate is signed with the secret key of the blesser
+(<code>S<sub>alice</sub></code>). The blessing can therefore be viewed as making
+the statement
+
+> <code>P<sub>alice</sub></code> using name <code>alice</code> says that
+> <code>P<sub>tv</sub></code> can use the name
+> <code>alice/devices/hometv</code>
+
+Blessing names are thus hierarchical, with
+slashes used to distinguish the blesser (`alice`) from the blessee
+(`devices/hometv`).
+
+## Caveats
+
+In practice, delegation of authority is never unconditional and this is
+supported by the security model. Blessings can carry caveats that restrict the
+conditions under which the blessing can be used. For example, a principal
+(<code>P<sub>alice</sub>, S<sub>alice</sub></code>) can bless
+another principal (<code>P<sub>bob</sub>, S<sub>bob</sub></code>)
+as `alice/houseguest/bob` but with the caveat that the blessing can only be used
+to talk to her TV (and not to remote services that Alice uses).
+This caveat is specified in the certificate written by `alice` (for Bob's public key
+<code>P<sub>bob</sub></code>). Thus the blessing makes a signed statement of
+the form:
+
+> <code>P<sub>alice</sub></code> using name <code>alice</code> says that
+> <code>P<sub>bob</sub></code> can use the name
+> <code>alice/houseguest/bob</code> _as long as_<br>
+ * <code>server</code> matches `alice/devices/hometv`
+
+When Bob presents this blessing to a server, the server will recognize the
+principal as `alice/houseguest/bob` only if the server's own blessing name
+matches `alice/devices/hometv`.
+
+Caveats can be placed on any information available at the time of the request.
+This includes, among other things, the time the request is being made, whether
+the blessing wielder is a client or a server, the communication protocol being
+used and the method being invoked.
+
+### Third-party caveats
+
+Validation of some caveats may involve expensive computation or I/O or
+information not accessible to the authorizing service. In such cases, the
+blesser can push the burden of validation to a _third party_ (i.e., neither the
+ party that wields the blessings nor the party that is authorizing them). For
+example, Alice can allow Bob to use the blessing `alice/houseguest/bob` only if
+bob is within 100 feet of Alice's home. When bob wants to authenticate as
+`alice/houseguest/bob`, he must obtain a _discharge_ (proof) from the third-party
+service `home_proximity_discharger` (mentioned in the caveat) before he can
+use the name `alice/houseguest/bob`. Thus the blessing makes the signed
+statement:
+
+> <code>P<sub>alice</sub></code> using name <code>alice</code> says that
+> <code>P<sub>bob</sub></code> can use the name
+> <code>alice/houseguest/bob</code> _as long as_<br>
+ * <code>home_proximity_discharger</code> issues a discharge after validating that
+ <code>P<sub>bob</sub></code> is <code>"within 100 ft"</code> of it.
+
+By using such _third-party caveats_, the burden of making the network calls to
+obtain a discharge and the burden of any computation or I/O to validate the
+restrictions are moved to the wielder of the blessing and to the third-party respectively, away from the end at which the authorization decision is being made.
+
+## Validating blessings
+
+A blessing is considered valid in the context of an RPC if and only if
+- the blessing is cryptographically valid, i.e., each certificate in the
+ blessing's certificate chain has a valid signature.
+- all caveats associated with the blessing are valid in the context of the RPC
+- the blessing is recognized.
+
+A blessing is _recognized_ by a Vanadium application if and only if the
+application considers the blessing root as authoritative for the blessing name.
+(Recall that blessing root is the public key of the first certificate in the
+blessing's certificate chain.)
+
+For example, an application may consider the root
+<code>P<sub>popularcorp</sub></code> as authoritative on all blessing names
+that begin with `popularcorp`. Such an application would then recognize the
+blessing `popularcorp/products/tv` if it is rooted in
+<code>P<sub>popularcorp</sub></code>.
+
+All Vanadium applications are configured to consider certain blessing roots as
+authoritative for certain names, and this configuration may vary across
+applications.
+
+## Authorization
+
+In a remote procedure call, two authorization decisions need to be made:
+
+
+- Does the client trust the server enough to __make__ a call? Making a call
+ reveals the identity of the client (i.e., its blessings), the object being
+ manipulated, the method being invoked and the arguments.
+- Does the server allow the client to invoke a _method_ on an _object_ with
+ the provided _arguments_?
+
+Both these decision are made using the following principle:
+<center><h4>Authorization is based on validated blessing names</h4></center>
+
+For example, a client may wish to invoke the `Display` method on a service only
+if the server presents a blessing matching the pattern `alice/devices/hometv`.
+Similarly, the service may allow a client to invoke the `Display` method only
+if the client presents a blessing matching the pattern `alice/houseguest`.
+
+The public keys of the client and server principals do not matter as long as
+they present a blessing with a valid name matching the other end's
+authorization policy. Each end ascertains the valid blessing name of the other
+end by validating all caveats associated with the blessing and verifying that the
+blessing is recognized.
+
+A pattern is a blessing name that may optionally end in a `/$`. If the pattern
+ends in a `/$``, it is only matched by the exact blessing name. Otherwise, it
+is matched by the blessing name and all its extensions.
+
+For example, the pattern `alice/houseguest` will be matched by the name `alice/houseguest`
+and its extensions (e.g., `alice/houseguest/bob`) but
+not by the name `bob` or `alice/colleague` or prefixes of the pattern (i.e.
+`alice`). On the other hand, the pattern `alice/houseguest/$` would be matched
+exactly by the name `alice/houseguest`.
+
+### Selecting a blessing
+
+A principal may have collected multiple blessings and may need to choose which
+subset of them to present when authenticating with a peer. It could present
+all, at the cost of leaking sensitive information (e.g., `bob` is a houseguest
+of `alice`) when not necessary. Instead Vanadium provides a means to
+selectively share blessings with appropriate peers.
+
+All blessings for a principal are stored in a _blessing store_, akin to a
+cookie jar in web browsers. The store marks the blessings to be presented when
+acting as a server (and a server always reveals its blessings first as per the
+[Vanadium authentication protocol]). Clients select a subset of their blessings
+from the store to share with a server based on the blessing names of the
+server.
+
+For example, Bob's blessing store can add the blessing `alice/houseguest/bob`
+to the store only to be shared with servers matching the pattern `alice`.
+Thus, all servers run by alice (such as `alice/hometv` and `alice/homedoor`)
+will see the `alice/houseguest/bob` blessing when Bob makes requests to them,
+but any other servers that Bob communicates with will not know that he has this
+blessing from Alice.
+
+## FAQs
+
+- **What is the plan for storing keys and blessings?**
+
+ All "credentials" of a principal (its private key, blessings, recognized blessing
+ roots) are stored in a `V23_CREDENTIALS` directory on the file
+ system. In the short term, the private key is kept encrypted at rest and
+ decoded in memory by an 'agent' process. The 'agent' process is the only one
+ with access to the private key and can audit usage of the key, similar to how
+ 'ssh-agent' works. Longer term, we envision wider use of [TPM]s and the key
+ being kept securely in them.
+
+- **Why is authorization based on blessing patterns as opposed to fixed
+ blessing names?**
+
+ The main motivations for using patterns (as opposed to fixed strings) for
+ authorization are to encourage delegation, enable auditing, and discourage
+ insecure workarounds. For example, if Alice's tv authorizes based on the
+ pattern `alice/houseguest`, then an authorized principal Bob with the
+ blessing `alice/houseguest/bob` can delegate Carol to use the tv by blessing
+ her with the name `alice/houseguest/bob/friend` (with appropriate caveats).
+ This name would match the blessing pattern `alice/houseguest`. By making
+ safely constrained delegation easy, Vanadium aims to discourage insecure
+ workarounds. If delegates were not authorized and Bob really wanted to share
+ access to Alice's tv with Carol, he may be tempted to work around the
+ restriction by running a proxy service for Carol. Alternatively, he could
+ create a new private key, get that blessed as `alice/houseguest/bob` and
+ share the key with Carol. By making blessings and patterns easy to use
+ instead, Bob is discouraged from trying out these hacks.
+
+ Having said that, patterns can also terminate with a `$` which forbid
+ delegation. So the pattern `alice/$` will only be matched by the blessing
+ name `alice` and not by `alice/houseguest` etc. While this facility does
+ exist, application developers and administrators are encouraged to think hard
+ about why they want to disallow delegation and whether doing so will
+ encourage hacky, insecure workarounds.
+
+- **Why does the pattern `alice/houseguest` not match prefixes like `alice`?**
+
+ The pattern `alice/houseguest` matches the blessing name `alice/houseguest`
+ and any delegates like `alice/houseguest/bob` or `alice/houseguest/carol`,
+ but not `alice` itself. Doing so does not really prevent `alice` from
+ accessing the resource, as `alice` can generate the blessing name
+ `alice/houseguest/foo` for herself at any time. However, this does protect
+ against accidental use of authority.
+
+ Think of how `sudo` works in UNIX-based systems. Users with `sudo` access can
+ act as the superuser, but they must explicitly do so by invoking the `sudo`
+ command. Similar to that, `alice` can generate the blessings required to
+ access resources protected by the pattern `alice/houseguest`, but she must
+ explicitly choose to do so by blessing herself.
+
+- **The authorization story described above demonstrates that there are two
+ ways to authorize a client to invoke methods at a server: (1) add the
+ blessing names of the client to the access list, or (2) bless the client,
+ providing it with a blessing name (with caveats) that matches an existing
+ entry in the access list. Which method is appropriate?**
+
+ The appropriate method of authorization would depend on who wants to
+ authorize whom and why. For example, consider these simple questions:
+
+ - _Do you have the ability to change the access list?_
+
+ It is likely that only `alice` can change the access list on the tv
+ (since she owns it). Thus, if `alice/houseguest/bob` wants to provide
+ `carol` with access to the tv, his options are to either bless `carol` or
+ find `alice` and trouble her to change the access list or try workarounds
+ like proxying the RPC.
+
+ On the other hand, if `alice` knows that `dave` should be able to access
+ the tv then she can add `dave` to the access list and avoid the need to
+ communicate with `dave` (to bless him) first.
+
+ - _Are there conditions on the access?_
+
+ Blessings allow for caveats on their use. For example,
+ `alice/houseguest/bob` can only be used within 100ft of the house. For
+ simplicity, Vanadium currently intends to support such caveats only on
+ blessings and keep access lists as simple lists of patterns (instead of
+ being able to specify arbitrary caveats in the access list).
+
+- **What are the privacy implications of exchanging blessings using the
+ [Vanadium authentication protocol]? **
+
+ Blessings can often contain [personally identifiable information] such as
+ usernames and email addresses, and therefore revealing them to unauthorized
+ parties poses a privacy risk. (Note that revealing blessings to unauthorized parties
+ does not pose a security or authorization risk as the blessings can
+ only be used by the principal they are bound to.)
+
+ The [Vanadium authentication protocol] ensures that blessings are always exchanged
+ over an encrypted channel and thus are protected from passive eavesdroppers.
+ Protecting blessings from active attackers -- ones that can pose as a
+ legitimate peer to the client or the server -- is more challenging. The protocol protects
+ the client's blessings from being revealed to unauthorized recipients at the cost of
+ revealing the server's blessings to all clients.
+
+ Servers always reveal their blessings first. This means that any client can learn the
+ server's blessings by making a request to the server. The server can choose what
+ blessings it authenticates with, and it is advisable that the server only choose blessings
+ that it is comfortable revealing to all clients.
+
+ Clients reveal their blessings only after seeing the server's blessings.
+ Clients can control the blessings revealed to individual servers by tagging blessings with
+ _server patterns_ in their [blessing stores](#selecting-a-blessing).
+ A server pattern is a blessing pattern indicating that the specific blessing it accompanies can
+ only be revealed to servers that have a blessing name matching the pattern.
+
+ For example, if a client has a blessing `alice/houseguest` tagged with the pattern
+ `alice/devices` in its blessing store then the blessing will only be revealed to servers that have
+ blessings matching the pattern `alice/devices` (e.g.,`alice/devices/tv`).
+ Other services (e.g., `carol/homedoor`) that the client communicates with will never see
+ this blessing and thus never learn that the client is Alice's _houseguest_.
+
+[TLS]: http://en.wikipedia.org/wiki/Transport_Layer_Security
+[ECDHE]: http://en.wikipedia.org/wiki/Elliptic_curve_Diffie%E2%80%93Hellman
+[Public-key cryptography]: http://en.wikipedia.org/wiki/Public-key_cryptography
+[key pair]: http://en.wikipedia.org/wiki/Public-key_cryptography
+[Public-key certificate]: http://en.wikipedia.org/wiki/Public_key_certificate
+[Forward-secrecy]: http://en.wikipedia.org/wiki/Forward_secrecy
+[NaCl box]: http://nacl.cr.yp.to/box.html
+[Vanadium authentication protocol]: ../designdocs/authentication.md
+[TPM]: http://en.wikipedia.org/wiki/Trusted_Platform_Module
+[Simple Distributed Security Infrastructure]: http://people.csail.mit.edu/rivest/sdsi11.html#secoverview
+[personally identifiable information]: http://en.wikipedia.org/wiki/Personally_identifiable_information
diff --git a/designdocs/authentication.md b/designdocs/authentication.md
new file mode 100644
index 0000000..5f4104c
--- /dev/null
+++ b/designdocs/authentication.md
@@ -0,0 +1,129 @@
+# Authentication protocol
+
+<!-- TODO(sadovsky): Fix embedded img tags. -->
+<!-- TODO(sadovsky): Fix godoc links. -->
+
+When a network connection is established between two Vanadium processes, they
+authenticate each other, i.e., exchange blessings so that both ends can
+identify the specific principal at the other end. The remote blessing names are
+then used to authorize RPCs. This document describes:
+- the properties desired from the authentication protocol
+- the current implementation that provides these properties
+- the reasons behind various design choices in a question-and-answer format.
+
+## Principals & blessings
+
+A [principal] is defined by a unique (public, private) key pair `(P, S)` and a
+set of blessings in the form of certificate chains that bind a name to `P`.
+For more details, read [security concepts].
+
+Within the Go codebase, the set of blessings is encapsulated within the
+[`v.io/v23/security.Blessings`] type. The principal and all private key
+operations are encapsulated in the [`v.io/v23/security.Principal`] type.
+
+## Authentication
+
+Communication between two processes takes place after they establish a
+confidential, authenticated connection. Encryption with keys derived from an
+[Elliptic curve Diffie-Hellman] (ECDH) exchange is used to provide message
+confidentiality and integrity . The goal of the authentication protocol is to
+exchange the blessings in a way that provides the following properties:
+
+1. _Session binding_: The private counterpart `S` of the public key `P` to
+ which the blessings are bound must be possessed by the same process with
+ which the session encryption keys have been established.
+2. _Client Confidentiality_: An eavesdropper listening in on all communication between
+ the two processes cannot determine the set of blessings presented by the initiator of
+ the connection (the "Client").
+
+## Current implementation
+
+As of April 2015, the reference implementation of the Vanadium networking stack
+in [`v.io/x/ref/runtime/internal/rpc/stream`] provides confidential,
+authentication communication streams (referred to as virtual circuits or VCs).
+Blessings bound to the public key used to establish the communication stream
+are provided with each RPC request.
+
+In this implementation, [NaCl/box] is used to establish an [authenticated-encryption]
+channel based on an ECDH key exchange.
+
+
+Where:
+- `{foo}k` represents the message `foo` encrypted using the key `k`
+- Channel bindings C1 and C2 at the Client and Server ends respectively are
+ constructed by appending a specific tag to the (sorted) pair of [NaCl/box]
+ public keys generated for the session. The tags are different for the Client
+ and Server ends, and are meant to prevent [type
+ flaws](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.106.6010&rep=rep1&type=pdf).
+ The public key is a 32-byte string distinct from the public key `P` to which
+ the blessings are bound.
+- If the Client is not happy with the blessing names presented by the Server,
+ it can abort the connection without ever revealing its blessings.
+
+### Code pointers
+
+Pointers to code in the reference implementation of the Vanadium APIs:
+- Session encryption is encapsulated in the [`Crypter`](https://github.com/vanadium/go.ref/blob/master/profiles/internal/rpc/stream/crypto/crypto.go) interface
+- [NaCl/box implementation of the
+ interface](https://github.com/vanadium/go.ref/blob/master/profiles/internal/rpc/stream/crypto/box.go)
+- The authentication protocol is implemented by the `AuthenticateAsClient` and
+ `AuthenticateAsServer` functions in
+ [`v.io/x/ref/runtime/internal/rpc/stream/vc/auth.go`](https://github.com/vanadium/go.ref/blob/master/profiles/internal/rpc/stream/vc/auth.go).
+
+## Questions
+
+- *Why don't the the Client and Server send their blessings in parallel,
+ instead of Server first?*
+
+ Doing so provides Client privacy.
+
+ If the Client sent its blessings before validating that it trusts the Server,
+ then an active network intermediary can learn the Client's blessings
+ and compromise Client privacy as it will learn of the Client's intention to
+ communicate.
+
+- *Can an intermediary fake a blessing by modifying messages between the Client
+ and Server?*
+
+ No.
+
+ Since all messages are exchanged using a negotiated encryption key, the only
+ malicious intermediary to consider is one that breaks the connection and
+ establishes separate encrypted sessions with the Client and Server. Doing so
+ will result in different channel bindings and the processes will realize that
+ they are not directly connected.
+
+ This session binding technique is inspired by Dirk Balfanz and Ryan Hamilton's
+ [channel ids] proposal.
+
+- *Did you consider using TLS instead of NaCl/box?*
+
+ Initially, TLS was used instead of NaCl/box to establish the encrypted
+ sesssion. However, only a stripped down version was needed (since TLS
+ was used only for establishing an encrypted session, not for authentication
+ via exchange of blessings) and the libraries being used made this more
+ heavy-weight than NaCl/box. For example, using TLS required 3 round-trips
+ to establish the session keys while with NaCl/box, a single round-trip
+ suffices.
+
+- *Why are blessings encrypted with the session key?*
+
+ The reason is threefold:
+
+ - To bind the session key to the blessings presented by each end. By encrypting its
+ blessings under the session key (using an [authenticated-encryption] scheme) each end
+ proves knowledge of the session key to the other end.
+ - To prevent passive network sniffers from determining the blessings being
+ exchanged over a network connection.
+ - To prevent active network attackers from learning the Client's blessings.
+
+[authenticated-encryption]: http://en.wikipedia.org/wiki/Authenticated_encryption
+[security concepts]: ../concepts/security.md
+[Elliptic curve Diffie-Hellman]: http://en.wikipedia.org/wiki/Elliptic_curve_Diffie%E2%80%93Hellman
+[session resumption is not used]: https://secure-resumption.com/#channelbindings
+[channel ids]: http://tools.ietf.org/html/draft-balfanz-tls-channelid-00
+[principal]: ../glossary.md#principal
+[`v.io/v23/security.Blessings`]: https://godoc.v.io/pkg/v.io/v23/security/#Blessings
+[`v.io/v23/security.Principal`]: https://godoc.v.io/pkg/v.io/v23/security/#Principal
+[`v.io/x/ref/runtime/internal/rpc/stream`]: https://godoc.v.io/pkg/v.io/x/ref/runtime/internal/rpc/stream
+[NaCl/box]: https://godoc.org/golang.org/x/crypto/nacl/box
diff --git a/designdocs/identity-service.md b/designdocs/identity-service.md
new file mode 100644
index 0000000..fbe0044
--- /dev/null
+++ b/designdocs/identity-service.md
@@ -0,0 +1,218 @@
+# Identity Service
+
+<!-- TODO(sadovsky): Fix embedded img tags. -->
+
+The [Vanadium Identity Service][`identityd`] generates [blessings][blessing].
+It uses an [OAuth2] identity provider to get the email address of a user and
+then issues a blessing with that email address. For example, after determining
+that the user is `alice@university.edu` (using OAuth2), this service will issue
+the blessing `dev.v.io/u/alice@university.edu` (where `dev.v.io` is
+the namespace for which the public key of the identity service is considered
+authoriative). The blessing may also contain specific caveats per the user's
+request.
+
+Broadly, this identity service consists of two main components:
+
+- **HTTPS Authentication Service**: This service authenticates the user using
+ an OAuth2 Identity Provider, and securely hands out a token (henceforth
+ called a macaroon) that encapsulates the user's authenticated identity and
+ any caveats that the user may have requested to be added to the blessing. The
+ cryptographic construction of macaroons ensures that their contents cannot be
+ tampered with.
+- **Vanadium Blessing Service**: This is a Vanadium RPC service with a method
+ that exchanges the macaroon for a blessing. The principal invoking this RPC
+ is blessed with a name and caveats extracted from the presented macaroon.
+
+One additional service enables revocation of the blessings granted by the
+blessing service:
+
+- **Vanadium Discharge Service**: This is a Vanadium RPC service enables
+ revocation. The service issues [discharges][discharge] for a revocation
+ [caveat] if the blessing has not been revoked by the user. The discharges are
+ valid for 15 minutes.
+
+All three services are exposed by a single binary - [`identityd`]. In order to
+save users from talking to two different services (the HTTP service and the
+Blessing service) and managing macaroons, we also provide a command-line tool -
+[`principal`] - that talks to both of the services and obtains a blessing for
+the principal that the tool is running as.
+
+## Preliminaries
+
+Before diving into the details of [`identityd`]'s design, some prerequisites:
+
+- [Principals, Blessings and Caveats](../concepts/security.md).
+- Third-party caveats: In a nutshell, a third-party caveat is a restriction on
+ the use of a blessing that must be validated by a party other than the two
+ communicating with and authorizing each other. The [blessing] with a
+ third-party caveat is considered valid only if accompanied by a [discharge]
+ issued by the third party that validated the restrictions. Discharges are
+ unforgeable and cryptographically bound to the correpsonding third-party
+ caveat.
+- _Macaroons_: For the purposes of the identity service, a macaroon is a bearer
+ token, similar to a cookie that can only be minted (and verified) by the
+ identity service. A macaroon encapsulates state whose bits cannot be tampered
+ with by anyone but the identity service. The state itself though is visible
+ to the bearers of the macaroon. In particular, the identity service with a
+ secret [HMAC] key `k` defines a macaroon for a state as:
+ <code>Macaroon<sub>k</sub>(state) = HMAC(k, state)</code>
+ The name "cookie" or "token" could have been used instead, but the term
+ macaroon was an allusion to [this
+ paper](http://research.google.com/pubs/archive/41892.pdf).
+
+## Service interfaces
+
+The HTTPS Authentication Service runs at https://dev.v.io/auth and uses the
+Google OAuth2 [web service flow] for authenticating users. It has a specific
+OAuth2 ClientID and ClientSecret obtained from the Google Developer Console. It
+supports the following routes:
+
+Route |Purpose
+------------------------|-----------------------------------
+`/google/seekblessings` | Receive blessing requests
+`/google/caveats` | Display a form for selecting caveats to be added to a blessing
+`/google/sendmacaroon` | Receive a POST request from the caveat selection form
+`/google/listblessings` | Enumerate all blessings made by a particular user
+`/google/revoke` | Receive revocation requests
+
+The blessing service is a Vanadium RPC service reachable via the name
+`/ns.dev.v.io:8101/identity/dev.v.io/u/google` and presents the [`MacaroonBlesser`](https://github.com/vanadium/go.ref/blob/master/services/identity/identity.vdl) interface:
+```
+type MacaroonBlesser interface {
+ // Bless uses the provided macaroon (which contains email and caveats)
+ // to return a blessing for the client.
+ Bless(macaroon string) (blessing security.WireBlessings | error)
+}
+```
+
+## Blessing flow
+
+The [`principal`] command-line tool is used to orchestrate the process of
+obtaining a macaroon from the HTTPS Authentication Service and exchanging it
+for a blessing from the Vanadium Blessing Service. The following sequence
+diagram lists the network requests involved in this process:
+
+
+
+- Solid-line arrows represent HTTPS requests (except one HTTP to localhost).
+- Dotted-line arrows represent Vanadium RPC requests.
+
+Steps 1 thru 4 in the sequence diagram above result in the [`principal`] tool
+invocation obtaining a macaroon.
+
+Steps 5 and 6 exchange that macaroon for a blessing.
+
+1. The tool generates a random state parameter `toolState` and starts an HTTP
+ server on `localhost` for receiving the macaroon. `toolURI` denotes the URI
+ of this server (e.g., `http://127.0.0.1:14141`), and `toolPublicKey` denotes
+ the public key of the principal running the tool.
+ It then directs the web browser on the machine to the HTTP Authentication
+ Service while informing it of `toolURI`, `toolPublicKey` and the `toolState`
+ parameters. For example, it might redirect to:
+ `https://dev.v.io/auth/google/seekblessings?redirect_uri=<toolURI>&state=<toolState>&public_key=<toolPublicKey>`
+
+2. The HTTP Authentication Service extracts `toolURI`, `toolState` and
+ `toolPublicKey` and redirects the browser to the Google OAuth2 endpoint
+ (using the [web service flow]). The `redirect_uri` provided to this endpoint
+ is set to the page that presents a form to control caveats on the final
+ blessing and the `state` parameter is set to: <code>oauthstate = Macaroon<sub>k</sub>(toolURI +
+ toolState + toolPublicKey + serverCookie)</code> where `serverCookie` is a
+ cookie set by the HTTP Authentication Service in the user's browser. This leads
+ the user's browser to a URL like:
+ `https://accounts.google.com/o/oauth2/auth?client_id=...&redirect_uri=https://dev.v.io/auth/google/caveat&state=oauthstate`
+
+ The Google OAuth2 endpoint asks the user to login and grant access to email
+ address to the Vanadium Identity Server, after which it redirect the browser
+ back to:
+ `https://dev.v.io/auth/google/caveats?code=<authcode>&state=<oauthstate>`
+
+3. The caveats page at the HTTP Authentication Service receives `authcode` and
+ `oauthstate`. It then:
+ - Verifies that `oauthstate` is a valid macaroon generated by step 2.
+ - Extracts `toolURI`, `toolState`, `toolPublicKey` and `serverCookie` from the macaroon.
+ - Verifies that `serverCookie` matches the cookie presented by the browser
+ - Exchanges `authcode` for an email address (via an identity token) using
+ the OAuth2 client-secret.
+ - Displays a form for selecting caveats to be added to the blessing that
+ will ultimately be provided to the [`principal`] tool started in step 1.
+ Embedded in this form is `formstate = Macaroon<sub>k</sub>(toolURI + toolState + toolPublicKey + email + serverCookie)`.
+
+4. When the user submits the form rendered in step 3, the browser sends the form
+ contents to `https://dev.v.io/auth/google/sendmacaroon` which performs the
+ following steps:
+ - Verifies that `formstate` is a valid macaroon.
+ - Extracts `toolURI`, `toolState`, `toolPublicKey`, `email` and `serverCookie` encapsulated
+ in the macaroon.
+ - Verifies that `serverCookie` matches the cookie presented by the browser.
+ - Verifies that `toolURI` is a localhost URI.
+ - Computes <code>M = Macaroon<sub>k</sub>(email, toolPublicKey, caveats)</code>.
+ - Redirects the browser to:
+ `https://<toolURI>/macaroon?state=<toolState>&macaroon=M&root_key=publicKey`
+ where `publicKey` is the [blessing root] of the identity service.
+
+5. The `principal` tool receives the macaroon `M`, `toolState` and the
+ [blessing root] via the HTTP redirect in step 4. It then:
+ - Verifies that `toolState` obtained here matches the one created in step 1.
+ - Invokes the `Bless` RPC on the blessing service passing it `M` as an argument.
+ It only sends this request if the the RPC server proves that it's public key
+ is `publicKey` via the [authentication protocol] used in RPCs.
+
+6. The Vanadium Blessing Service that receives this RPC performs the following steps:
+ - Verifies that the macaroon presented is valid.
+ - Extracts `email`, `toolPublicKey` and `caveats` from it.
+ - Verifies that the principal making the RPC request has the same public key
+ as `toolPublicKey`. This check ensures that the macaroon can only be used by
+ the principal tool that requested it in the first place. It protects against
+ impersonation attacks wherein an attacker steals the macaroon handed out in
+ step 5 and then tries to obtain a blessing for the email address encapsulated
+ in the macaroon.
+ - Generates a [blessing] with the name `dev.v.io/u/<email>` and the
+ caveats extracted from the macaroon. This blessing is bound to the public
+ key of the principal making the RPC request (i.e., `toolPublicKey`).
+ - Records the creation of this blessing in a database which can be queried via
+ `https://dev.v.io/auth/google/listblessings`.
+
+## Supported caveats
+
+The caveat addition form presented to the user in step 4 supports a few types
+of caveats:
+
+- [_Expiry_]: Which limits the time period during which the blessing is valid.
+- [_PeerBlessings_]: Which limits the set of peers that the blessing will be recognized by.
+- [_Method_]: Which limits the set of methods that can be invoked with the blessing.
+- [_Revocation_]: Which allows the user to revoke the blessing at any time in
+ the future by visiting https://dev.v.io/auth/google/listblessings.
+
+### Revocation
+
+The revocation caveat that is (at the user's request) added to the blessing is
+a third-party caveat with a unique 16-byte ID and the object name of the
+discharging service. Each time a revocation caveat is created, the blessing
+service stores the corresponding ID and the revocation status in a SQL
+database.
+
+The [discharge service] run by [`identityd`] extracts the ID from the caveat
+and looks it up in the database. If the database suggests that blessing should
+be revoked, it refuses to issue a discharge.
+
+This is implemented in
+[services/identity/internal/revocation](https://github.com/vanadium/go.ref/tree/master/services/identity/internal/revocation).
+
+Revocation can be triggered by clicking buttons on https://dev.v.io/auth/google/listblessings.
+
+
+[`identityd`]: https://github.com/vanadium/go.ref/tree/master/services/identity/identityd
+[blessing]: ../glossary.md#blessing
+[discharge]: ../glossary.md#discharge
+[OAuth2]: http://oauth.net/2/
+[caveat]: ../glossary.md#caveat
+[HMAC]: http://en.wikipedia.org/wiki/Hash-based_message_authentication_code
+[`principal`]: https://github.com/vanadium/go.ref/tree/master/cmd/principal
+[web service flow]: https://developers.google.com/accounts/docs/OAuth2WebServer
+[blessing root]: ../glossary.md#blessing-root
+[authentication protocol]: authentication.md
+[_Expiry_]: https://github.com/vanadium/go.v23/blob/master/security/caveat.vdl
+[_Method_]: https://github.com/vanadium/go.v23/blob/master/security/caveat.vdl
+[_PeerBlessings_]: https://github.com/vanadium/go.v23/blob/master/security/caveat.vdl
+[_Revocation_]: https://github.com/vanadium/go.ref/tree/master/services/identity/internal/revocation
+[discharge service]: https://github.com/vanadium/go.ref/blob/master/services/discharger/discharger.vdl
diff --git a/designdocs/vdl-spec.md b/designdocs/vdl-spec.md
new file mode 100644
index 0000000..df256ed
--- /dev/null
+++ b/designdocs/vdl-spec.md
@@ -0,0 +1,592 @@
+# VDL specification
+
+<!-- TODO(sadovsky): Fix godoc links. -->
+
+This is a reference manual for VDL, the Vanadium Definition Language. The intended audience is both end-users writing VDL files, as well as core developers implementing VDL.
+
+VDL is an interface definition language for describing Vanadium components. It is designed to enable interoperability between implementations executing in heterogeneous environments. E.g. it enables a frontend written in JavaScript running on a phone to communicate with a backend written in Go running on a server. VDL is compiled into an intermediate representation that is used to generate code in each target environment.
+
+Communication in Vanadium is based on remote procedure calls. The main concepts in VDL map closely to concepts in general-purpose languages used to specify interfaces and communication protocols.
+
+## Goals
+There are three main goals for VDL. These goals form the core of what a VDL user is trying to accomplish, and also inform tradeoffs in language design and features. VDL tries to make accomplishing these goals simple.
+
+### Specify the wire format
+The main reason to write VDL is to define the wire format between different components. This is a prerequisite for interoperability; in order to implement a server that may be called by any client in any language, the wire format between the components needs to be defined.
+
+VDL defines its own type and value system, with well-defined semantics. The VOM (Vanadium Object Marshalling) protocol defines mappings from values of every VDL type to a wire format. The combination of VDL and VOM enables a simple yet powerful mechanism to specify wire protocols.
+
+### Specify the API
+Once a common wire format has been established between components, we need an API to access the functionality in our desired programming environment. E.g. a JavaScript frontend that needs to invoke methods on a Go backend needs a standard way to access that functionality.
+
+APIs are specified by compiling VDL to your target environment. The VDL compiler converts VDL concepts into idiomatic native constructs in your target environment.
+
+### Usage is optional
+The last goal is to ensure the usage of VDL is optional. Users have a choice to forgo VDL if it doesn't adequately benefit their usage scenario. E.g. two JavaScript components may choose to communicate directly as full-fledged Vanadium components, without using VDL at all.
+
+## Syntax
+The VDL syntax is based on the Go language, which has a compact and regular grammar.
+
+### Comments
+There are two forms of comments:
+1. Line comments start with the character sequence `//` and stop at the end of the line. A line comment acts like a newline.
+2. General comments start with the character sequence `/*` and continue through the character sequence `*/`. A general comment containing one or more newlines acts like a newline, otherwise it acts like a space.
+
+Comments do not nest.
+
+### Semicolons
+The grammar uses semicolons `;` as terminators in many productions. Idiomatic VDL omits most of these semicolons using the following two rules:
+1. When the input is broken into tokens, a semicolon is automatically inserted into the token stream at the end of a non-blank line if the line's final token is an identifier, literal (string_lit, integer_lit, rational_lit, or imaginary_lit), or closing fence (`)`, `]`, `}` or `>`).
+2. A semicolon may be omitted before a closing `)` or `}`.
+
+### Identifiers
+Identifiers name entities such as types and methods. An identifier is a sequence of one or more ASCII letters and digits. The first character of an identifier must be a letter. We intentionally restrict to ASCII to more naturally support common generated languages.
+```
+identifier = [A-Za-z][A-Za-z0-9_]*
+```
+Examples of valid identifiers:
+```
+a
+this_is_an_identifier_
+AsIsThis
+```
+Identifiers may either be exported or unexported. Exported identifiers may be used by other packages; unexported identifiers may not. An identifier is exported if the first character is uppercase `[A-Z]`. Most identifiers are required to be exported in VDL; exceptions to this rule are noted.
+```
+notExported
+alsoNotExported
+ThisIsExported
+```
+
+Here is a complete list of VDL keywords. Keywords may not be used as identifiers.
+```
+const enum error import interface map package
+set stream struct type typeobject union
+```
+
+### Built-in identifiers
+The following identifiers are built-in, and used to bootstrap the language to make it useful. All built-in identifiers are available for use within other packages.
+```
+// Built-in types
+any bool byte error string typeobject
+complex64 complex128
+float32 float64
+int16 int32 int64
+uint16 uint32 uint64
+
+// Built-in constants
+false true nil
+```
+
+### Example
+Here is a simplified example of two single-file VDL packages that showcase most of the main concepts.
+```
+// File: example/bignum/bignum.vdl
+
+// All vdl files must start with a package clause.
+package bignum
+
+// Named types may be created based on any other type.
+type Int string // arbitrary-precision integer
+
+// Constants are unchanging values of any type.
+const (
+ MaxInt8 = Int("127")
+ MinInt8 = Int("-128")
+)
+```
+<!--separate code blocks-->
+```
+// File: example/arith/arith.vdl
+
+package arith
+
+import (
+ "time" // time is a standard package
+ "example/bignum" // bignum is the package above
+)
+
+// Status is a conjunction of many fields.
+type Status struct {
+ Wall, Cpu time.Duration
+ Alg Algorithm
+}
+
+// Enum types have no mapping to numeric values.
+type Algorithm enum {Sieve;Elliptic}
+
+// Constants of any type may be expressed.
+const UnknownStatus = Status{Wall: -1, Cpu: -1, Alg: Sieve}
+
+// Interfaces define a set of methods, along with a name.
+type Arith interface {
+ // Add returns x + y.
+ Add(x, y bignum.Int) (bignum.Int | error)
+
+ // Div returns x / y, or the DivByZero error.
+ Div(x, y bignum.Int) (bignum.Int | error)
+}
+
+// Interfaces may embed other interfaces.
+type Advanced interface {
+ // Arith is embedded in the Advanced interface;
+ // Advanced contains the methods Add, Div, Factor.
+ Arith
+ // Factor demonstrates output streaming; 0 or more Status
+ // values are returned before the factors.
+ Factor(x bignum.Int) stream<_,Status> ([]bignum.Int | error)
+}
+
+// Errors may be defined for use across languages.
+error DivByZero() {"en": "divide by zero"}
+```
+
+## Packages
+VDL is organized into packages, where a package is a collection of one or more source files. The files in a package collectively define the types, constants, interfaces and errors belonging to the package. Those elements may in turn be used in another package.
+
+Each source file consists of a package clause, followed by a (possibly empty) set of imports, followed by a (possibly empty) set of definitions.
+```
+SourceFile = PackageClause ";" {Import ";"} {Def ";"}
+Def = TypeDef | ConstDef | InterfaceDef | ErrorDef
+
+PackageClause = "package" PackageName
+PackageName = identifier
+```
+A package clause begins each source file, and defines the package to which the file belongs. A set of files in the same directory sharing the same PackageName form the definition of a package. By convention the PackageName is the basename of the directory containing the source files.
+```
+package bignum
+```
+
+## Standard packages
+
+VDL comes with a collection of standard packages, which define common types and
+interfaces that may be used by all applications. E.g. the
+[time package](https://godoc.v.io/src/v.io/v23/vdlroot/time/time.vdl) defines a
+standard representation of time, to promote compatibility across different
+computing environments.
+
+The current set of [standard packages](https://godoc.v.io/src/v.io/v23/vdlroot)
+is small, and will grow over time to provide more standardized representations
+of core concepts.
+
+## Imports
+An import states that the source file containing the import depends on the imported package, and enables access to the exported identifiers of that package. Cyclic dependencies are not allowed. The PackageName is used as the first component of a QualifiedName, and is used to access identifiers of that package within the importing source file. If the PackageName is omitted, it defaults to the identifier specified in the PackageClause of the imported package.
+```
+Import = "import" ImportSpec
+ | "import" "(" [ ImportSpec {";" ImportSpec} [";"] ] ")"
+
+ImportSpec = [PackageName] ImportPath
+ImportPath = string_lit
+QualifiedName = PackageName "." identifier
+NameRef = QualifiedName | identifier
+```
+Examples of imports:
+```
+import "time"
+import big "example/bignum"
+```
+
+## Types
+A type specifies a set of valid values. The set of valid types is partitioned into different kinds, where each kind of type specifies its own rules determining the valid set of values.
+```
+// Built-in scalar type kinds
+bool // boolean true / false
+string // sequence of UTF8 runes
+byte // unsigned byte (8 bits)
+uint{16,32,64} // unsigned integer
+int{16,32,64} // signed integer
+float{32,64} // IEEE 754 floating point
+complex{64,128} // complex number, both parts floating point
+typeobject // type represented as a value
+
+// User-defined scalar and composite type kinds
+enum // one of a set of labels
+array // fixed-length ordered sequence of elems
+list // variable-length ordered sequence of elems
+set // unordered collection of distinct keys
+map // unordered mapping between distinct keys and elems
+struct // conjunction of ordered sequence of fields
+union // disjunction of ordered sequence of fields
+
+// Variant type kinds
+any // value can be of any type
+optional // value might not exist
+```
+
+Types may be named or unnamed. All built-in types are named with the name of their kind. Types defined using the `type` keyword are named by the user. The `any` and `typeobject` type kinds *cannot* be named by the user; all other kinds *can* be named by the user, and the `enum`, `struct` and `union` type kinds *must* be named by the user. These naming rules strike a balance between expressibility in the VDL and practical limitations for generated code.
+
+`bool` represents boolean true and false values.
+
+`string` represents a human-readable sequence of UTF8 runes. Arbitrary binary data should not be represented using strings, instead use an `array` or `list` of bytes.
+
+`byte` represents a single unsigned 8-bit byte.
+
+`uint` represents unsigned integers of 16, 32 or 64 bits.
+
+`int` represents signed integers of 16, 32 or 64 bits.
+
+`float` represents IEEE 754 floating point numbers of 32 or 64 bits.
+
+`complex` represents complex numbers, where both the real and imaginary parts are floating point numbers. Complex64 is composed of two 32 bit floats, while complex 128 is composed of two 64 bit floats.
+
+`typeobject` represents a type as a value; types are also first-class values. This is used to represent method signatures, and pass type information between components.
+
+`enum` represents a choice between a finite set of labels. There is no concept of a corresponding numeric value; the label determines the choice.
+
+`array` represents a fixed-length ordered sequence of elements, all of the same type.
+
+`list` represents a variable-length ordered sequence of elements, all of the same type.
+
+`set` represents an unordered collection of distinct keys, all of the same type.
+
+`map` represents an unordered association between distinct keys and elements, where all keys are of the same type, and all elements are of the same type.
+
+`struct` represents a conjunction of an ordered sequence of fields, where each field is a (name,type) pair.
+
+`union` represents a disjunction of an ordered sequence of fields, where each field is a (name,type) pair.
+```
+TypeDef = "type" TypeSpec
+ | "type" "(" [ TypeSpec {";" TypeSpec} [";"] ] ")"
+TypeSpec = TypeName TypeExpr
+TypeName = identifier
+TypeExpr = NameRef
+ | "error"
+ | "enum" "{" Label {";" Label} [";"] "}"
+ | "[" integer_lit "]" TypeExpr
+ | "[" "]" TypeExpr
+ | "set" "[" TypeExpr "]"
+ | "map" "[" TypeExpr "]" TypeExpr
+ | "struct" "{" [ Field {";" Field} [";"] ] "}"
+ | "union" "{" [ Field {";" Field} [";"] ] "}"
+ | "?" TypeExpr
+Label = identifier
+Field = FieldName {"," FieldName} TypeExpr
+```
+Examples of type definitions:
+```
+type Int string
+type Algorithm enum {Sieve;Elliptic}
+type Status struct {
+ Wall, Cpu time.Duration
+ Alg Algorithm
+}
+```
+
+## Constants
+A constant represents an immutable value. Constants may be typed or untyped. There are six categories of constants, representing various typed and untyped combinations. Typed constants may represent any valid value for their kind of type. Untyped integer, rational and complex constants are collectively called numerics, and have "infinite" precision; they do not overflow or underflow.
+
+```
+category untyped constant type kind
+-------- ---------------- ---------
+boolean untyped boolean bool
+string untyped string string, []byte
+integer untyped integer byte, {u,}int{16,32,64}
+rational untyped rational float{32,64}
+complex untyped complex complex{64,128}
+misc enum, typeobject, array, list,
+ set, map, struct, union
+```
+
+The following constants are built-in:
+```
+false: Untyped boolean constant
+true: Untyped boolean constant
+nil: Represents non-existent optional value
+```
+
+## Literals
+There are four categories of scalar literals: string, integer, rational and imaginary. Each literal represents its respective untyped constant, where the imaginary literal represents an untyped complex constant with real part zero.
+```
+string_lit = /* e.g. "abc" `def` */
+integer_lit = /* e.g. 0 123 0644 0xDeadBeef */
+rational_lit = /* e.g. 0. .25 42.3 1e6 .123e+3 */
+imaginary_lit = /* e.g. 0i 0.i 123i .25i 1e6i .12e+3i */
+```
+
+Composite literals are also supported, and represent arrays, lists, sets, maps, structs and unions. The type of every composite literal needs to be known in order for it to be compiled. The full syntax is in the grammar; informally it looks like:
+```
+TypeExpr{key0:elem0, key1:elem1, ...}
+```
+
+The TypeExpr may be explicitly provided, or as a convenience, the TypeExpr may be elided for composite literals within a parent composite literal where the type may be implied.
+
+Array and list literals have optional keys and required elems, and each elem is assigned to list[index]. If a key is provided, the index is set to the key converted to a uint64; otherwise the index is set to one more than the previous index, or 0 if key0 isn't provided.
+
+Set literals have required keys and may not specify elems. Map literals have required keys and elems.
+
+Struct literals must either have all keys provided, or no keys provided. If keys are provided they are identifiers that must match field names of the struct, and the matching field is set to elem. If keys are not provided, the fields of the struct are set in order, and the number of elems must exactly match the number of fields in the struct.
+
+Union literals must specify a single `key:elem` pair, where the key must match a single field name of the union.
+
+Enum constants are specified using the selector syntax.
+```
+type Mode enum {Fast;Slow}
+
+// Enum constant
+const MyMode = Mode.Fast
+```
+
+Typeobject constants are specified using syntax similar to explicit type conversions.
+```
+type Foo struct {A int32;B string}
+
+// Typeobject constants
+const (
+ MyFooType = typeobject(Foo)
+ MyFooListType = typeobject([]Foo)
+)
+```
+
+## Operators
+Logical, bitwise, comparison and arithmetic operators are supported. Not all operators support all constants. The following table shows the operators and the supported constant categories.
+```
+// Unary operator (boolean)
+! // logical not
+
+// Unary operator (integer)
+^ // bitwise not
+
+// Unary operator (integer, rational, complex)
++ - // no-op | negate
+
+// Binary operator (all)
+== != // equal, not equal
+
+// Binary operator (boolean)
+&& || // logical {and,or}
+
+// Binary operator (integer)
+% // mod
+& | ^ // bitwise {and,or,xor}
+<< >> // shift {left,right}
+
+// Binary operator (integer, rational, string)
+< <= > >= // less{,equal} greater{,equal}
+
+// Binary operator (integer, rational, complex)
++ // add
+- * / // sub, mul, div
+```
+
+Binary operators are of the form `x op y`. If x and y are both typed constants, their types must be identical. If either x or y (or both) are untyped constants, the values are implicitly converted to a common type before performing the operation.
+
+## Conversions
+Implicit conversions of untyped constants obey the following rules:
+```
+implicit conversion details
+------------------- -------
+untyped integer -> untyped rational Allowed
+untyped rational -> untyped complex Allowed
+untyped complex -> untyped rational Only if 0 imaginary
+untyped rational -> untyped integer Only if 0 fractional
+untyped integer -> {byte,uint,int}* Only if no overflow
+untyped rational -> float* Only if no overflow,
+ may lose precision
+untyped complex -> complex* Only if no overflow,
+ may lose precision
+```
+
+Explicit conversions of scalars add the following rules:
+```
+explicit scalar conversion details
+-------------------------- -------
+same kind -> same kind Allowed
+string -> []byte Allowed
+[]byte -> string Only if bytes are UTF8
+enum -> {string,[]byte} Allowed, uses label
+{string,[]byte} -> enum Only if label is valid
+{byte,uint,int}* -> {byte,uint,int}* Only if no overflow
+{byte,uint,int}* -> float* Only if no loss
+ of precision
+float* -> {float,complex}* Allowed,
+ may lose precision
+complex* -> complex* Allowed,
+ may lose precision
+complex* -> float* Only if 0 imaginary,
+ may lose precision
+float* -> {byte,uint,int}* Only if 0 fractional,
+ and if no overflow
+```
+
+Explicit conversions of composites add the following rules:
+```
+ explicit
+composite conversion details
+-------------------- -------
+{array,list} -> array Only if elems are convertible,
+ and if src len <= dst array len
+{array,list} -> list Only if elems are convertible
+set -> set Only if keys are convertible
+set -> map Only if keys are convertible,
+ result type map[key]bool
+map -> set Only if keys are convertible,
+ and if map elem is bool or struct{}
+map -> map Only if keys and elems
+ are convertible
+struct -> map Only if field names and elems
+ are convertible
+struct -> struct Only if fields with matching names
+ are convertible
+ [unknown fields ignored]
+map -> struct Only if fields with matching keys
+ are convertible
+ [unknown fields ignored]
+```
+
+## Evaluation and definition
+Named constants are defined using the const keyword. Named consts and method tags are fully evaluated to a final value. Intermediate results of const expressions may remain untyped, but final const values must be typed. This restriction ensures const expression evaluation always occurs within the VDL compiler, and all generated code uses identical const values. Otherwise we'd be at the mercy of the compilers / interpreters for the generated languages, which has a wide variance in expression evaluation semantics.
+```
+ConstDef = "const" ConstSpec
+ | "const" "(" [ ConstSpec {";" ConstSpec} [";"] ] ")"
+ConstSpec = ConstName "=" ConstExpr
+ConstName = identifier
+ConstExpr = UnaryExpr | ConstExpr binary_op ConstExpr
+UnaryExpr = PrimaryExpr | unary_op UnaryExpr
+PrimaryExpr = NameRef
+ | NameRef "(" ConstExpr ")"
+ | "(" ConstExpr ")"
+ | PrimaryExpr "." identifier
+ | "typeobject" "(" TypeExpr ")"
+ | string_lit | integer_lit | rational_lit | imaginary_lit | CompLit
+binary_op = "||" | "&&" | "==" | "!=" | "<" | "<=" | ">" | ">=" |
+ "+" | "-" | "*" | "/" | "%" | "|" | "&" | "^" | "<<" | ">>"
+unary_op = "!" | "+" | "-" | "^"
+CompLit = [TypeExpr] "{" [ KVLit {"," KVLit} [","] ] "}"
+KVLit = [KLit ":"] VLit
+KLit = ConstExpr
+VLit = ConstExpr | CompLit
+```
+Examples of const definitions:
+```
+const (
+ MaxInt8 = Int("127")
+ MinInt8 = Int("-128")
+ Five = int32(2 + 3)
+ UnknownStatus = Status{Wall: -1, CPU: -1}
+)
+```
+
+## Interfaces
+An interface represents a set of methods. Every interface has an InterfaceName. Interfaces can embed other interfaces by referring to their InterfaceName. This adds all methods of the embedded interface to the set of methods in the embedding interface. Duplicate names are allowed, but only if the method signatures are identical. Code generation for some languages may add additional semantics; e.g. object-oriented languages may use embedding as a signal for an inheritance relationship.
+
+Every method is named and contains optional InArgs, InStream and OutStream types, OutArgs and Tags. The InArgs and OutArgs are positional, and arg names idiomatically start with a lowercase letter. A single underscore "_" may be used as the InStream or OutStream type, which means there is no respective in or out stream type. Idiomatic usage only uses the underscore if there is no InStream, but there is an OutStream type.
+
+The general flow for a method call is as follows:
+* MethodName and InArgs are dispatched to the receiver.
+* A sequence of InStream and OutStream values may be sent and received, respectively. The exact protocol depends on the semantics of the method.
+* OutArgs are returned to the caller.
+
+Tags are only used as metadata, and are not sent to the receiver during the actual method call. Each tag const expression is evaluated to a final result by the compiler, and the generated code provides a mechanism to retrieve the tags. Tags are typically used as method annotations; e.g. each method might be annotated with a security permissions specifying access control. Idiomatic usage uses the type of each tag to determine the appropriate behavior.
+```
+InterfaceDef = "type" InterfaceSpec
+ | "type" "(" [ InterfaceSpec {";" InterfaceSpec} [";"] ] ")"
+InterfaceSpec = InterfaceName "interface" "{" [ MethodOrEmbed {";" MethodOrEmbed} [";"] ] "}"
+InterfaceName = identifier
+MethodOrEmbed = Method | NameRef
+Method = MethodName "(" [InArgs] ")" [StreamTypes] [OutArgs] [Tags]
+MethodName = identifier
+Args = Field {"," Field} [","]
+ | TypeExpr {"," TypeExpr} [","]
+InArgs = Args
+OutArgs = "error"
+ | "(" Args "|" "error" ")"
+StreamTypes = "stream" "<" [ InStream [ "," OutStream ] ] ">"
+InStream = TypeExpr
+OutStream = TypeExpr
+Tags = "{" [ ConstExpr {"," ConstExpr} [","] ] "}"
+```
+Examples of interface definitions:
+```
+type Arith interface {
+ Add(x, y bignum.Int) (bignum.Int | error)
+ Div(x, y bignum.Int) (bignum.Int | error) {"tag"}
+}
+type Advanced interface {
+ Arith
+ Factor(x bignum.Int) stream<_,Status> ([]bignum.Int | error)
+}
+```
+
+## Errors
+An error represents an exceptional condition. VDL defines a built-in `error` type which enables interoperability of error creation and checking across computing environments. E.g. VDL errors are generated as error values in Go, while they're generated as exceptions in Java. The core libraries allow you to check for occurrences of specific errors, even if the error was generated in a different process, or a different programming language.
+
+The wire format of the VDL `error` looks like this:
+```
+type RetryCode enum {
+ NoRetry // Do not retry.
+ RetryConnection // Retry high-level connection/context.
+ RetryRefetch // Refectch and retry (e.g., out of date version).
+ RetryBackoff // Backoff and retry a finite number of times.
+}
+
+type error struct {
+ Id string // Identity of the error.
+ Msg string // Error message, generated based on Id and ParamList.
+ RetryCode RetryCode // Suggested retry behavior upon receiving this error.
+ ParamList []any // Variadic parameters associated with the error.
+}
+```
+
+Specific error instances may be defined in VDL. This generates code in each native language, to make it easy to create and check errors. Each error includes a unique identifier, which is automatically created with the form `PackagePath.ErrorName`. E.g. an error definition with name `Foo` in package path `"a/b/c"` results in error id `"a/b/c.Foo"`.
+```
+ErrorDef = "error" ErrorSpec
+ | "error" "(" [ ErrorSpec {";" ErrorSpec} [";"] ] ")"
+ErrorSpec = ErrorName "(" [InArgs] ")" ErrorDetails
+ErrorName = identifier
+ErrorDetails = "{" ErrorDetail {"," ErrorDetail} [","] "}"
+ErrorDetail = ErrorAction
+ | ErrorLang ":" ErrorFmt
+ErrorAction = identifier
+ErrorLang = string_lit
+ErrorFmt = string_lit
+```
+Examples of error definitions:
+```
+error (
+ NoParams1() {"en":"en msg"}
+ NoParams2() {RetryRefetch, "en":"en msg"}
+ WithParams1(x string, y int32) {"en":"en x={x} y={y}"}
+ WithParams2(x string, y int32) {
+ RetryRefetch,
+ "en":"en x={x} y={y}",
+ "fr":"fr y={y} x={x}",
+ }
+)
+```
+
+## Config files
+Config files are a mechanism to specify configuration information to a program. E.g. a command line program may need to be configured with directory paths for input or output. Since VDL already has syntax to represent types and constants, it is natural to use the same syntax to represent configuration information.
+
+A config file exports a single constant, and may contain one or more imports and constants. All constants representable in regular VDL are representable in config files, using the same syntax.
+
+Each config file consists of a config clause, followed by a (possibly empty) set of imports, followed by a (possibly empty) set of const definitions. The config clause defines the exported constant via a ConstExpr. As with regular constant expressions, the config clause definition may be an inline definition, or may simply name a const defined elsewhere in the file.
+```
+ConfigFile = ConfigClause ";" {Import ";"} {ConstDef ";"}
+ConfigClause = "config" "=" ConstExpr
+```
+Examples of config files:
+```
+// File: 0.config - inline definition
+// (implicit type arith.Status)
+config = {0, 0, arith.Algorithm.Sieve}
+```
+<!--separate code blocks-->
+```
+// File: 1.config - using imports
+config = foo
+
+import "example/arith"
+
+const (
+ foo = arith.Status{0, 0, arith.Algorithm.Sieve}
+ bar = arith.Status{1, 1, arith.Algorithm.Elliptic}
+)
+```
+
+Config files only contain constant definitions; types, interfaces and errors may not be specified within config files. It is idiomatic to define a struct type specifying the format of the config file in a package, and export a constant of that type from the config file.
+
+Config files that use more than the built-in types need to import the packages defining the necessary types. As a commonly-used exception to this rule, an implicit type may be provided to the config file compiler. The implicit type is used to specify the type of the exported constant, if it is a composite literal that don't have an explicit type. This allows the succinct inline definition syntax to be used, without specifying any imports.
+
+All valid config files must start with "config". However "config" is not itself a keyword in the grammar; it may be used as a regular identifier.
+
+### vdl.config
+The vdl tool is an example of a command-line program that requires configuration; e.g. there are options for code generation in each native language. Each vdl package directory may contain a special `vdl.config` file, representing the configuration for that vdl package. The `vdl.config` file is written in the generic VDL config file syntax, exporting a constant with type [vdltool.Config](https://godoc.v.io/src/v.io/v23/vdlroot/vdltool/config.vdl). An example is the [vdl.config file](https://godoc.v.io/src/v.io/v23/vdlroot/time/vdl.config) for the standard time package.
diff --git a/designdocs/vom-spec.md b/designdocs/vom-spec.md
new file mode 100644
index 0000000..bb57a23
--- /dev/null
+++ b/designdocs/vom-spec.md
@@ -0,0 +1,301 @@
+# VOM specification
+
+Vanadium Object Marshalling (VOM) is a data format capable of serializing all
+values representable in [VDL]. It is the underlying serialization format used
+by the Vanadium [RPC] system.
+
+VOM is a binary format that represents a stream of typed values. The sending
+side sequentially encodes values into a stream of bytes, and the receiving side
+decodes the stream of bytes back into the original sequence of values.
+
+The format is self-describing. Given all data generated by an encoder, a
+generic decoder with no a priori knowledge of the contents can recover the types
+and values that were originally encoded. This enables support for reflection,
+and allows generic tools to be written to process the data. E.g. a storage
+system might use VOM to encode user-provided values into its log files.
+Specific fields of the data may be indexed for fast lookups, and the log files
+may be decoded even if the original encoding program no longer exists.
+
+## Binary format
+
+VOM is a byte-based binary format, consisting of a sequence of messages. Each
+message is either a type definition (`TypeMsg`) or a value definition
+(`ValueMsg`). Types must be defined before they are instantiated by values.
+
+The format starts with a single version byte, which must be `0x80` for the
+initial version of VOM.
+
+### Grammar
+The format is described by the following grammar:
+
+```
+// VOM starts with a version byte, followed by a sequence of messages.
+VOM: version Message*
+// Each message defines either a type or a value. Both kinds of messages
+// start with a typeid, and are distinguished by whether the typeid is
+// positive or negative.
+Message: TypeMsg | ValueMsg
+
+// Type messages start with a negative ID that identifies the type,
+// followed by the WireType that defines the type, encoded just like
+// any other main value.
+TypeMsg: -typeid MainValue(WireType)
+
+// Value messages start with a positive ID that references a previously
+// defined type, which describes the static type of the value,
+// followed by the main value encoding.
+ValueMsg: +typeid MainValue
+
+// If the main value is a primitive, its encoding is based on its type.
+// Otherwise it's a composite, which starts with the unsigned byte length
+// of the rest of the encoding, followed by the composite encoding.
+MainValue: primitive | bytelen CompositeV
+// Other values (e.g. elements of an list) are encoded like the main value,
+// without the byte length prefix for composites.
+Value: primitive | CompositeV
+
+// Composite values have various encodings based on the kind of type.
+CompositeV: SeqV | SeqPairV | SparseSeqV | ElemV | OptV | AnyV
+// Arrays, lists and sets are encoded as a dense sequence, starting with
+// the unsigned number of items, followed by that many elements.
+SeqV: num Value*{num}
+// Maps are encoded as a dense sequence of pairs, starting with the
+// unsigned number of entries, followed by that many (key, elem) pairs.
+SeqPairV: num (Value Value)*{num}
+// Structs are encoded as a sparse sequence of (index, field) pairs.
+// The index is the 0-based unsigned index of the struct field.
+// Zero-valued fields are skipped, and fields may be encoded in any order.
+// The fields are terminated by an END control byte.
+SparseSeqV: (index Value)* END
+// Unions are encoded as a single (index, field) pair.
+// The index is the 0-based unsigned index of the union field.
+ElemV: index Value
+// Optional is encoded as either a NIL control byte representing
+// non-existence, or the value.
+OptV: NIL | Value
+// Any is encoded as either a NIL control byte representing
+// non-existence, or the unsigned type ID followed by the value.
+AnyV: NIL | typeid Value
+```
+
+All rules in the above grammar terminate in primitive values; the entire VOM
+encoding comprises combinations of primitives. The encoding of primitive values
+is in turn based on a single concept called var128.
+
+### Var128
+
+The basis for VOM encoding is var128, a variable-length unsigned integer with a
+maximum size of 128 bits (16 bytes). This is a byte-based encoding. Values in
+the range [0, 127] are encoded verbatim in a single byte. Larger values use the
+first byte to encode the byte length of the value, with subsequent bytes
+encoding the value in its minimal big-endian representation.
+
+The first byte of the encoding is the crux of the encoding. Of the 256 possible
+states for the first byte, 128 states are used to represent the values [0, 127],
+and another 16 states are used to represent the multi-byte lengths [1, 16].
+That leaves 112 states, which are reserved for control entries.
+
+<table>
+<thead>
+<tr><th>var128 first byte</th><th>7</th><th>6</th><th>5</th><th>4</th><th>3</th><th>2</th><th>1</th><th>0</th></tr>
+</thead>
+<tbody>
+<tr><td><strong>0x00..0x7F</strong><br>Single byte value</td><td>0</td><td colspan=7>value in range [0, 127]</td><tr>
+<tr><td><strong>0x80..0xBF</strong><br>Control1<br>(64 entries)</td><td>1</td><td>0</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><tr>
+<tr><td><strong>0xC0..0xDF</strong><br>Control2<br>(32 entries)</td><td>1</td><td>1</td><td>0</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><tr>
+<tr><td><strong>0xE0..0xEF</strong><br>Control3<br>(16 entries)</td><td>1</td><td>1</td><td>1</td><td>0</td><td>-</td><td>-</td><td>-</td><td>-</td><tr>
+<tr><td><strong>0xF0..0xFF</strong><br>Multi-byte length<br>(FF=1, FE=2, ...)</td><td>1</td><td>1</td><td>1</td><td>1</td><td colspan="4">len in range [1, 16]</td><tr>
+</tbody>
+</table>
+
+The encoding of the value and control entries are disjoint from each other; each
+var128 can either hold a single value of up to 128 bits, or a control entry with
+112 possible states, grouped in consecutive 4, 5 and 6 bit chunks. The encoding
+favors small values; values less than 128 and all control entries are encoded in
+a single byte.
+
+This is based on the fundamental format for the Go [gob] encoding, with the
+addition of the control entries. This format strikes a balance between size and
+speed; we try not to be wasteful of space, but still keep the format simple and
+fast to encode and decode.
+
+### Control entries
+
+The var128 control entries are used to represent special properties in the VOM
+encoding. We take advantage of the fact that control entries may appear at the
+same position where regular values are expected, and distinguished
+appropriately.
+
+Most control entries are currently unused, but reserved for future expansion.
+
+<table>
+<tbody>
+<tr><th>0xE0</th><td>NIL</td><td>Represents a non-existent value</td></tr>
+<tr><th>0xE1</th><td>END</td><td>Represents the end of a sequence</td></tr>
+</tbody>
+</table>
+
+### Primitives
+
+Primitives types are encoded using either var128 or raw bytes.
+
+* Bool: Encoded directly as a single raw byte; 0 means false and 1 means true.
+* Byte: Encoded directly as a single raw byte.
+* Unsigned integer: Encoded directly as a var128.
+* Signed integer: Encoded as a var128, with bits 1 and up containing the value,
+ and bit 0 indicating whether to complement the other bits to recover the
+ signed integer.
+* Floating point: Encoded as a var128 containing a byte-reversed [IEEE 754]
+ 64-bit float.
+* Complex number: Encoded as two consecutive floats, the first representing the
+ real component and the second representing the imaginary component.
+* String: Encoded as a var128 containing the byte length, followed by that many
+ raw bytes.
+
+### Built-in types
+
+A fixed set of built-in types are used to bootstrap the encoding format, and are
+assumed to be known by both the encoder and decoder. Each built-in type has a
+fixed type ID. The semantics of the built-in types are defined by the
+[VDL type system].
+
+<style>
+.z {
+ padding-top: 1px;
+ padding-bottom: 1px;
+}
+.c {
+ padding-top: 1px;
+ padding-bottom: 1px;
+ text-align: center;
+}
+</style>
+<table>
+<tbody>
+<tr><th class="z">ID</th><th class="z">Built-in type</th></tr>
+<tr><th class="c" colspan=2>Primitive types</th></tr>
+<tr><td class="z">1</td><td class="z">`bool`</td></tr>
+<tr><td class="z">2</td><td class="z">`byte`</td></tr>
+<tr><td class="z">3</td><td class="z">`string`</td></tr>
+<tr><td class="z">4</td><td class="z">`uint16`</td></tr>
+<tr><td class="z">5</td><td class="z">`uint32`</td></tr>
+<tr><td class="z">6</td><td class="z">`uint64`</td></tr>
+<tr><td class="z">7</td><td class="z">`int16`</td></tr>
+<tr><td class="z">8</td><td class="z">`int32`</td></tr>
+<tr><td class="z">9</td><td class="z">`int64`</td></tr>
+<tr><td class="z">10</td><td class="z">`float32`</td></tr>
+<tr><td class="z">11</td><td class="z">`float64`</td></tr>
+<tr><td class="z">12</td><td class="z">`complex64`</td></tr>
+<tr><td class="z">13</td><td class="z">`complex128`</td></tr>
+<tr><td class="z">14</td><td class="z">`typeobject`</td></tr>
+<tr><td class="z">15</td><td class="z">`any`</td></tr>
+<tr><th class="c" colspan=2>Composite types</th></tr>
+<tr><td class="z">39</td><td class="z">`[]byte`</td></tr>
+<tr><td class="z">40</td><td class="z">`[]string`</td></tr>
+<tr><th class="c" colspan=2>User defined types</th></tr>
+<tr><td class="z">41</td><td class="z">first user defined type id</td></tr>
+</tbody>
+</table>
+
+### Wire types
+
+User defined types are described in values of type `WireType`, and encoded into
+`TypeMsg` just like regular values. Unlike the regular encoding process,
+`WireType` cannot result in the generation of further type messages; there must
+be an end to the recursion. Similar to the built-in types, `WireType` and its
+sub types are assumed to be known by both the encoder and decoder, for
+bootstrapping purposes.
+
+The space of all types consists of the built-in types, and user-defined types
+as described by `WireType`.
+
+`WireType` and associated sub types are defined as follows. Since these types
+are used to bootstrap the system, the ordering of fields within each of these
+types is fixed and cannot be changed.
+
+```
+// WireType represents a user-defined type, and is encoded into the
+// payload portion of each type message.
+type WireType union {
+ NamedT WireNamed // INDEX = 0
+ EnumT WireEnum // INDEX = 1
+ ArrayT WireArray // INDEX = 2
+ ListT WireList // INDEX = 3
+ SetT WireSet // INDEX = 4
+ MapT WireMap // INDEX = 5
+ StructT WireStruct // INDEX = 6
+ UnionT WireUnion // INDEX = 7
+ OptionalT WireOptional // INDEX = 8
+}
+
+// TypeID uniquely identifies a type definition within a VOM stream.
+type TypeID uint64
+
+// WireNamed represents the definition of named primitive types.
+type WireNamed struct {
+ Name string // INDEX = 0
+ Base TypeID // INDEX = 1
+}
+
+// WireEnum represents the definition of enum types.
+type WireEnum struct {
+ Name string // INDEX = 0
+ Labels []string // INDEX = 1
+}
+
+// WireArray represents the definition of array types.
+type WireArray struct {
+ Name string // INDEX = 0
+ Elem TypeID // INDEX = 1
+ Len uint64 // INDEX = 2
+}
+
+// WireList represents the definition of list types.
+type WireList struct {
+ Name string // INDEX = 0
+ Elem TypeID // INDEX = 1
+}
+
+// WireSet represents the definition of set types.
+type WireSet struct {
+ Name string // INDEX = 0
+ Key TypeID // INDEX = 1
+}
+
+// WireMap represents the definition of map types.
+type WireMap struct {
+ Name string // INDEX = 0
+ Key TypeID // INDEX = 1
+ Elem TypeID // INDEX = 2
+}
+
+// WireField represents a field in a struct or union type.
+type WireField struct {
+ Name string // INDEX = 0
+ Type TypeID // INDEX = 1
+}
+
+// WireStruct represents the definition of struct types.
+type WireStruct struct {
+ Name string // INDEX = 0
+ Fields []WireField // INDEX = 1
+}
+
+// WireUnion represents the definition of union types.
+type WireUnion struct {
+ Name string // INDEX = 0
+ Fields []WireField // INDEX = 1
+}
+
+// WireOptional represents the definition of optional types.
+type WireOptional struct {
+ Name string // INDEX = 0
+ Elem TypeID // INDEX = 1
+}
+```
+
+[VDL]: vdl-spec.md
+[VDL type system]: vdl-spec.md#types
+[RPC]: ../concepts/rpc.md
+[gob]: http://golang.org/pkg/encoding/gob/
+[IEEE 754]: http://en.wikipedia.org/wiki/IEEE_floating_point
diff --git a/glossary.md b/glossary.md
new file mode 100644
index 0000000..cb57ac2
--- /dev/null
+++ b/glossary.md
@@ -0,0 +1,426 @@
+# Glossary
+
+## Access list
+
+An access list describes which [blessing names](#blessing-name) should be
+granted access to a particular object or method.
+
+An access list has an _In_ list of [blessing patterns](#blessing-pattern) that
+grants access to all blessing names that are matched by one of the patterns,
+and an optional _NotIn_ list that specifies exclusions from the _In_ list.
+
+For example, an access list with the _In_ list {`alice/family`} and _NotIn_
+list {`alice/family/uncle}` is matched by principals with blessing names
+`alice/family`, `alice/family/friend`, but NOT `alice`, `alice/friend`,
+`alice/family/uncle`, `alice/family/uncle/spouse`, and so on.
+
+See also: [Blessing patterns](#blessing-pattern) for the semantics of pattern
+matching, [Security Concepts].
+
+## Agent
+
+Agent is a utility for serving [credentials](#credentials) to applications
+analogous to an [ssh-agent]. The agent is used to protect private keys from
+vulnerabilities in the application. The private key is kept encrypted on disk
+and unencrypted in the memory of the agent process.
+
+Application processes that are descendants of the agent process can use the
+credentials (e.g., sign a message using the private key) by making requests to
+the agent process over inter-process communication channels.
+
+See also: [Security Concepts].
+
+## Blessing
+
+A blessing is a binding of a human-readable [name](#blessing-name) to a [principal](#principal),
+valid under some [caveats](#caveat), given by another principal.
+
+Principals are authorized for operations based on these names.
+
+The binding between the name, the principal and the caveats is cryptographically
+secured via a chain of [certificates](#certificate). A blessing bound to one
+principal cannot be used by another. Thus, the theft of blessings does not
+present a security risk.
+
+For example, a principal _Alice_ (with the key pair <code>(P<sub>alice</sub>,
+S<sub>alice</sub>)</code>) can bind the name `allie` (or any other name of her
+choosing) to herself with a self-signed certificate that binds the name `allie`
+to <code>P<sub>alice</sub></code>, with the caveat that this name can only be
+used for "read" operations. Since the blessing is based on a self-signed
+certificate, it is referred to as a [_self-blessing_](#self-blessing).
+
+When one principal blesses another, they do so by chaining a new certificate
+to one of their existing blessings. For example, consider the following two
+certificates:
+
+1. One that binds the __extension__ `friend` to the public key <code>P<sub>bob</sub></code>
+ with the caveat "use only between 9am and 5pm" _chained to_
+2. The `allie` certificate mentioned above.
+
+Both certificates chained together represent a blessing that binds the name
+`allie/friend` to _Bob_, but only for "read operations, between 9am and 5pm"
+(all the caveats in all the certificates in the chain).
+
+_Bob_ can then bless _Carol_ with the name `allie/friend/colleague` by chaining
+a new certificate, signed by <code>S<sub>bob</sub></code> to his `allie/friend`
+blessing.
+
+See also: [Security Concepts].
+
+## Blessing name
+
+A blessing name is the _human readable_ name extracted from a
+[blessing](#blessing). Principals are typically authorized based on the
+blessing names bound to them.
+
+For example, say a principal _Carol_ wishes to invoke the `Read` method on a
+service run by a principal _Alice_. The authorization decision is made after a
+sequence of steps:
+
+1. _Carol_ presents a set of blessings (bound to her public key) to _Alice_.
+2. _Alice_ looks at each presented blessing and discards those which have
+ [caveats](#caveats) that are not met in context of the method being invoked (or those which are not [recognized](#blessing-root)).
+3. _Alice_ then looks at the names of the remaining blessings and decides
+ whether _Carol_ is authorized to invoke the method or not based on the name.
+
+Two principals can have the same blessing name bound to them,
+allowing them to share authorization without sharing each other's secret
+private key.
+
+See also: [Security Concepts].
+
+## Blessing pattern
+
+A blessing pattern is a "pattern" that is matched by either a specific
+[blessing name](#blessing-name) or the blessing name and all its
+[extensions](#blessing).
+
+The pattern `<b>/$` is matched by the blessing name `<b>`, while the pattern `<b>`
+is matched by `<b>` and all its extensions.
+
+For example, the pattern `alice/houseguest` will be matched by the blessing
+name `alice/houseguest`, `alice/houseguest/bob`, `alice/houseguest/bob/friend`
+but not `alice/colleague`, `alice/houseguest2` or prefixes of the pattern like
+`alice` (for example `alicea` or `aliceb`). The pattern `alice/houseguest/$`
+would be matched only by the exact blessing name `alice/houseguest`.
+
+See also: [Security Concepts].
+
+## Blessing root
+
+The root of a blessing is the public key of the first certificate in the
+certificate chain of the blessing.
+
+A blessing is _recognized_ by an application if and only if the application
+considers the root of the blessing as being authoritative on the corresponding
+[blessing name](#blessing-name).
+
+For example, one application may recognize the root
+<code>P<sub>alice</sub></code> as an authority on blessings matching the
+pattern `allie`, such as `allie` and `allie/friend`. Other applications may
+not do so. Thus, when a blessing with the root <code>P<sub>alice</sub></code>
+is presented to them, they will discard this blessing when extracting [blessing
+names](#blessing-name).
+
+See also: [Security Concepts].
+
+## Caveat
+
+Caveats are conditions placed on a [blessing](#blessing) to restrict the
+validity of a [blessing name](#blessing-name). For example, caveats may restrict
+the time duration for which the blessing name can be used, or the set of peers
+that can be communicated with or the type of operations that can be performed.
+
+When two principals communicate via an [RPC](#remote-procedure-call-rpc-), they
+validate all the caveats in the blessings presented by the peer. In a
+client-server setting, the client validates caveats on the blessings presented
+by the server and vice-versa.
+
+Caveats are of two kinds -- first-party and third-party. First-party caveats
+are validated entirely by the party making an authorization decision on the
+blessings presented by the remote end.
+
+[Third-party caveats](#third-party-caveat) are validated by the specific
+third party mentioned in the caveat. The party making the authorization
+decision expects a proof of validity (i.e., a [Discharge](#discharge)) for the
+caveat from the third party.
+
+See also: [Security Concepts].
+
+## Certificate
+
+A certificate is an object consisting of a human-readable string name,
+a public key, a list of [caveats](#caveat), and a digital signature over
+its contents.
+
+Certificates can be _chained_ to form a [blessing](#blessing). The first
+certificate in the chain is _self-signed_, i.e., it is signed using the private
+counterpart of the public key mentioned in the certificate and is referred to
+as the _root certificate_.
+
+All other certificates in the chain are signed by the private counterpart of
+the public key mentioned in the previous certificate in the chain.
+
+See also: [Security Concepts].
+
+## Client
+
+A client is the caller-side of an [RPC](#remote-procedure-call-rpc-). Clients
+invoke methods on [servers](#server).
+
+## Credentials
+
+Credentials encompass a [principal](#principal) (i.e., a public-private key
+pair), the set of [blessings](#blessing) bound to that principal, and the set
+of recognized [blessing roots](#blessing-root).
+
+An application process retrieves its credentials from a directory containing
+this data, or from an [agent](#agent) that holds this data (including the
+private key of the principal) safely.
+
+## Discharge
+
+A discharge is a proof of validity of a [third-party
+caveat](#third-party-caveat) issued by the third party mentioned in the
+caveat. It is cryptographically tied to the particular caveat.
+
+A discharge may have [caveats](#caveat) of its own that limit the
+validity of the discharge.
+
+A discharge can be cached and reused, so it's not necessarily true
+that every attempt to use a blessing will incur the cost of obtaining
+a discharge.
+
+Discharges may expire, but the expiration time is typically broad
+enough to allow for clock skew.
+
+## Discharger
+
+A server that must be consulted to mint a [discharge](#discharge) for
+a caveat. A blessing is valid only if _all_ of its
+[third-party caveats](#third-party-caveat) are discharged.
+
+See also: [Security Concepts].
+
+## Endpoint
+
+An Endpoint is an encoding of all the information required to securely contact
+a [server](#server). Among other things, this includes the network address of
+the server, e.g.,`<IP address>:<port>` (tcp), or `<MAC address>` (bluetooth).
+
+## Identity provider
+
+An identity provider is a [principal](#principal) that signs [root
+certificates](#certificate) of [blessings](#blessing) with a fixed name.
+
+For an identity provider to be useful, an application must use
+[credentials](#credentials) that [recognize](#blessing-root) its public key as
+an authority on blessings extended from its name.
+
+For example, _Popular Corp_ could be an identity provider with public key
+<code>P<sub>popularcorp</sub></code> and name `popularcorp`. It could bless
+other principals with the name `popularcorp/<username>`. However, this identity
+provider will only be useful to other applications that recognize
+<code>P<sub>popularcorp</sub></code> as an authoritative key on blessing names
+beginning with `popularcorp/`.
+
+Root certificates (and thus identity providers) are recognized only for
+blessings matching a specific [pattern](#blessing-pattern). For example, an
+application might recognize the root <code>P<sub>popularcorp</sub></code> for
+blessings that match the pattern `popularcorp` and not for blessings that match
+`othercorp`. This prevents [certificate forging] where one recognized identity
+provider can issue certificates for an entity that is normally managed by
+another identity provider.
+
+Companies, schools, or other public agencies could become _identity providers_
+and application [credentials](#credentials) will be configured to recognize
+some subset of these. For example, services run for general consumption might
+trust a Google-run blessing service, while services run within a corporate
+setting would only recognize blessings whose root was a key owned by the
+corporation.
+
+See also: [Security Concepts].
+
+## Mount table
+
+A mount table is a [server](#server) that associates [object
+names](#object-name) with ([endpoint](#endpoint), [suffix](#suffix)) pairs.
+The endpoint identifies the server that hosts the named object, and the suffix
+is used to locate the object within the server.
+
+The process of associating a name (aka "mount point") with the (endpoint,
+suffix) pair of an object is called "mounting".
+
+Since the mount point is itself an object (on which the `Mount`
+[RPC](#remote-procedure-call-rpc-) can be invoked), it can be mounted on other
+mount points. This allows for the creation of a hierarchy of names, a
+[namespace](#namespace) of objects.
+
+See also: [Naming Concepts][naming-concepts].
+
+## Namespace
+
+A directed graph made up of [mount tables](#mount-table) that create a
+hierarchy of [object names](#object-name).
+
+A namespace may contain loops (it is not a DAG).
+
+## Object name
+###### Also called: Name
+
+An object name is a human-readable name of an object that exports methods on
+which [RPCs](#remote-procedure-call-rpc-) can be made.
+
+Object names are _resolved_ to a set of ([endpoint](#endpoint),
+[suffix](#suffix)) pairs via [mount tables](#mount-table). Invoking an RPC on an
+object implies sending the RPC to one of the pairs obtained by _resolving_ the
+object name.
+
+For example, the object name `alice/calendar/today` might _resolve_ to the
+[endpoint](#endpoint) of Alice's calendar server and the suffix `today`. The
+object might export methods `AddAppointment` and `RemoveAppointment`, which are
+invoked to manage Alice's calendar.
+
+See also: [Naming Concepts][naming-concepts].
+
+## Permissions
+
+Permissions are maps from string tags (like "Read" or "Admin") to [Access
+Lists](#access-list) specifying the blessings required to invoke methods with
+that tag.
+
+See also: [Security Concepts].
+
+## Principal
+
+A principal is a public and private [key pair].
+
+Every [RPC](#remote-procedure-call-rpc-) is executed on behalf of a principal.
+To encourage security, different processes and certainly processes on different
+devices run as different principals - each with their own private key. The
+private key should ideally be in secure storage such that it cannot be stolen
+from the device on which the application is being run.
+
+Applications should never share their private key or transmit it on the wire.
+Only public keys and [blessings](#blessing) should be transmitted. Multiple
+[blessings](#blessing) can be bound to a single principal.
+
+See also: [Security Concepts].
+
+## Remote Procedure Call (RPC)
+
+Remote procedure calls enable communications between processes by presenting
+an API based on function calls. The caller of an RPC is known as the
+[client](#client) and the receiver that implements the RPC is known as the
+[server](#server). Clients invoke methods implemented on the server, which is
+identified by its [object name](#object-name).
+
+See also: [RPC concepts][rpc-concepts].
+
+## Self-blessing
+
+A [blessing](#blessing) who's certificate chain has only one certificate,
+necessarily self-signed, since if it had been signed by another
+principal it would not be a single entry chain.
+
+A self-blessing is the starting point to issuing blessings to other
+principals.
+
+## Server
+
+A server is the receiver-side of an [RPC](#remote-procedure-call-rpc-).
+Servers implement methods that are invoked by [clients](#client).
+
+The term server is also used to refer to the process that hosts objects and
+dispatches RPC requests to the methods implemented by those objects.
+
+## Suffix
+
+A suffix is the trailing portion of an [object name](#object-name) used to
+identify the object within a server.
+
+For example, the object name `alice/calendar/today` may be hosted by a
+[server](#server) that hosts all objects with the prefix `alice/calendar`. In
+that case, the [RPC](#remote-procedure-call-rpc-)
+`alice/calendar/today.AddAppointment()` will be directed to this server and the
+suffix `today` will be used by the server to identify the object.
+
+## Third-party caveat
+
+_Third-party caveats_ are [caveats](#caveat) wherein the burden of validation
+is pushed to a specific _third party_ that is different from the request
+recipient.
+
+A blessing with a third-party caveat is considered valid only when accompanied
+by a [discharge](#discharge) (proof of validity) issued by the specific third
+party mentioned in the caveat. The third party validates the caveat before
+granting or denying a discharge.
+
+Examples of third-party caveats include _revocation_ caveats that are
+discharged by a specific revocation service if and only if the blessing has
+not been revoked, _proximity_ caveats that are discharged by a proximity
+service if and only if the requester satisfies the proximity constraints
+mentioned in the caveat, and _audit_ caveats that are discharged by an
+auditing service only after updating the audit log.
+
+It is the responsibility of the wielder of a blessing to fetch discharges for
+all third-party caveats present on the blessing. The wielder may cache
+discharges for as long as they are valid.
+
+See also: [Security Concepts].
+
+## v23
+
+The [atomic number of Vanadium][vanadium-element] is 23, which is the
+inspiration behind the `v23` shorthand for Vanadium. It is used broadly, from
+directory names to command-line flags and tools.
+
+See also: [v23 command-line tool](tools/v23.md), [Contribution instructions](community/contributing.md).
+
+## vrpc
+
+The `vrpc` command line tool sends and receives
+[RPCs](#remote-procedure-call-rpc-). It is used as a generic [client](#client)
+to interact with any [server](#server).
+
+## Vanadium Definition Language (VDL)
+
+VDL describes the API for interfaces provided by objects. This includes the set
+of methods that can be invoked via an [RPC](#remote-procedure-call-rpc-), their
+arguments and return types. These interfaces are described in `.vdl` files. The
+`vdl` command-line tool generates language-specific interfaces for these APIs.
+
+See also: [VDL specification][vdl-spec].
+
+## Vanadium Object Marshaling (VOM)
+
+VOM is the data serialization format used in Vanadium. It enables the
+encoding and decoding of typed values across different programming languages,
+e.g. Go, Java, and JavaScript.
+
+See also: [VOM specification][vom-spec].
+
+## WebSocket Proxy (WSPR)
+
+A server (usually called WSPR, pronounced *whisper*) allows JavaScript
+running in a web browser or Node.js to communicate with a Vanadium system.
+WSPR proxies the Vanadium world behind a WebSocket interface.
+
+A JavaScript app uses a Node.js module that implements a WebSocket front-end
+to WSPR. WSPR accepts requests from the app over the WebSocket, sends them on
+as conventional Vanadium RPCs, and returns the responses to the JavaScript app
+via WebSocket.
+
+WSPR as a concept will move from a freestanding server into a browser
+extension, and ultimately become native to browsers.
+
+[naming-concepts]: concepts/naming.md
+[rpc-concepts]: concepts/rpc.md
+[vdl-spec]: designdocs/vdl-spec.md
+[vom-spec]: designdocs/vom-spec.md
+[gob]: http://golang.org/pkg/encoding/gob/
+[key pair]: http://en.wikipedia.org/wiki/Public-key_cryptography
+[certificate forging]: https://www.linshunghuang.com/papers/mitm.pdf
+[ssh-agent]: http://en.wikipedia.org/wiki/Ssh-agent
+[vanadium-element]: http://en.wikipedia.org/wiki/Vanadium
+[Security Concepts]: concepts/security.md
diff --git a/tools/identity-service-faq.md b/tools/identity-service-faq.md
new file mode 100644
index 0000000..93a2d49
--- /dev/null
+++ b/tools/identity-service-faq.md
@@ -0,0 +1,80 @@
+# Vanadium Identity Service
+
+The Vanadium Identity Service is a cloud service that is a [blessing root] for
+blessing names that begin with `dev.v.io`. Applications can choose to
+[recognize][blessing root] the authority of this service in order to broker
+authentication between different [principals] that the application communicates
+with.
+
+The web interface for this service is accessible at https://dev.v.io/auth and
+the design of this service (along with how to obtain a blessing from it) is
+described in [this document][design-doc].
+
+Some frequently asked questions about this service follow.
+
+### What information is stored by the service?
+
+In order to obtain a blessing from this service, one must sign-in using their
+Google Account. For each blessing created by this service, the following is
+recorded:
+
+- Email address associated with the Google account that was used to
+ authenticate with the service
+- The timestamp at which the blessing was created
+- The certificate chain for the blessing
+
+Additionally, for each revocable blessing granted, the service also stores the
+timestamp at which the revocation happened (or the fact that the blessing has
+not yet been revoked).
+
+All user-information stored by this service is accessible to the owner of the
+Google Account at https://dev.v.io/auth/google/listblessings
+
+### Why is the default caveat a revocation caveat?
+
+When creating a blessing of the form `dev.v.io/users/<email_address>` (after
+using Google OAuth to determine the email address), the user is asked to select
+a set of caveats to be placed on the blessing.
+
+By default, this form is pre-populated with a _revocation caveat_, which means
+that the blessing is valid until explicitly revoked by the user. The user may
+chose to remove this default caveat and insert other caveats instead.
+
+Revocation (as opposed to say setting a short-lived expiration caveat) was chosen
+as the default for two reasons:
+
+1. Gives the user finer control over blessings issued to them.
+ The user can choose to revoke these blessings at any time, rendering them
+ ineffective.
+2. Allows the blessings to be long-lived. Blessings that aren't revoked are
+ always valid, so the user doesn't have to concern themselves with "managing"
+ the validity of blessings by keeping track of when they expire and when they
+ have to be re-issued.
+
+This choice of default may be revisited based on user feedback.
+
+### What information is provided to this service on discharge requests?
+
+Use of the revocation caveat implies that the granted blessing is valid only
+when accompanied with a [discharge] issued by the identity service. This means
+that use of the blessing requires a periodic RPC to the identity service in
+order to obtain the discharge. This request to obtain a discharge only
+sends information about the caveat, no information on why the discharge is
+being requested is sent to this service.
+
+### What are the terms of service for using the Vanadium Identity Service?
+
+Use of this service (including obtaining a blessing from it or listing
+blessings obtained from it) is subject to the [terms of service] of all cloud
+services hosted at v.io.
+
+### Where can I find the code that backs this service?
+
+https://github.com/vanadium/go.ref/services/identity/identityd/main.go
+
+[blessing root]: ../glossary.md#blessing-root
+[Vanadium Security Model]: ../concepts/security.md
+[principals]: ../glossary.md#principal
+[design-doc]: ../designdocs/identity-service.md
+[terms of service]: ../tos.md
+[discharge]: ../glossary.md#discharge
diff --git a/tools/services.md b/tools/services.md
new file mode 100644
index 0000000..919d747
--- /dev/null
+++ b/tools/services.md
@@ -0,0 +1,33 @@
+# Vanadium Cloud Services
+
+<!-- TODO(sadovsky): Fix godoc links. -->
+
+While it's possible to run all Vanadium infrastructure services on your own we host several of them to ease development overhead. The following services are available to use and are often the default values for most configurations. All services listed here are covered by the the [terms of service].
+
+## Mount table
+
+The [Mount table] is a service that allows other Vanadium applications to discover and address one another. To be discovered an application will mount itself at a "name" and other applications (clients) can then address the service.
+
+See also: [Naming Concepts], [`mounttable` Go documentation]
+
+## Identity service
+
+The Identity Service is an HTTP server that uses OAuth to create blessings. It allows users to "login" to a service and affords them the ability to generate and manage access credentials.
+Google runs such a service at https://dev.v.io/auth.
+
+See also: [Security Concepts], [identityd Go documentation], [Identity service FAQ]
+
+## Proxy service
+
+The Proxy Service listens for connections from Vanadium services (typically behind NATs) and proxies these services to the outside world.
+
+See also: [proxy Go documentation]
+
+[proxy Go documentation]: https://godoc.v.io/pkg/v.io/x/ref/services/proxy/
+[`mounttable` Go documentation]: https://godoc.v.io/pkg/v.io/x/ref/services/mounttable/
+[Mount table]: ../glossary.md#mount-table
+[Naming Concepts]: ../concepts/naming.md
+[Security Concepts]: ../concepts/security.md
+[identityd Go documentation]: https://godoc.v.io/pkg/v.io/x/ref/services/identity/identityd/
+[terms of service]: ../tos.md
+[Identity service FAQ]: identity-service-faq.md
diff --git a/tools/v23.md b/tools/v23.md
new file mode 100644
index 0000000..e5ce80e
--- /dev/null
+++ b/tools/v23.md
@@ -0,0 +1,9 @@
+# v23
+
+`v23` is a multi-purpose command-line tool designed to aid Vanadium
+development. After following the setup instructions for [contributing] you
+will have the `v23` tool in your `PATH` and can run:
+
+ v23 help
+
+[contributing]: ../community/contributing.md
diff --git a/tools/vanadium-chrome-extension.md b/tools/vanadium-chrome-extension.md
new file mode 100644
index 0000000..176b13e
--- /dev/null
+++ b/tools/vanadium-chrome-extension.md
@@ -0,0 +1,75 @@
+# Vanadium Chrome Extension
+
+<!-- TODO(sadovsky): Fix embedded img tags. -->
+
+The [Vanadium Chrome extension][] is a bridge between JavaScript web apps and
+the Vanadium runtime, libraries, and services.
+
+Support for web applications is a work-in-progress. Currently, Vanadium web
+apps can run only in the Chrome desktop browser with the [Vanadium Chrome
+extension][] installed. Mobile browsers and non-Chrome browsers will be
+supported in the future.
+
+## Overview
+
+The Vanadium codebase is written mostly in [Go][]. In order to make the Go
+libraries accessible to a JavaScript web app, the Vanadium Go code is compiled
+into a [Native Client][] (NaCl) plugin and embedded in a Chrome extension.
+
+[Native Client][] is a sandbox for running compiled binary code in
+the browser efficiently and securely, independent of the user's operating
+system type. These plugins can make use of the [Pepper API][].
+
+Traditionally, NaCl has supported only C and C++ compilation, but the Vanadium
+team has extended the Go compiler to target NaCl and the Pepper API.
+
+The [Vanadium JavaScript library][] provides a set of JavaScript APIs for
+interacting with the Vanadium Go code running inside the NaCl plugin in the
+extension.
+
+Under the hood, the Vanadium JavaScript library sends messages to the Vanadium
+extension, which makes calls to other Vanadium devices in the cloud. The
+extension sends messages back to the web app when those calls return, or when
+an external device initiates a call to the JavaScript client.
+
+
+
+Isolating the Vanadium libraries inside a NaCl plugin has the added benefit
+that no JavaScript web app ever sees any private keys. All cryptographic
+operations are performed within the extension's NaCl sandbox.
+
+## Vanadium Chrome extension details
+
+The Vanadium extension has two main components:
+ * a [content script][] that runs on each tab, and
+ * a [background page][] that runs once per browser and contains JavaScript code and a NaCl plugin.
+
+The following diagram depicts these components and the flow of messages between them.
+
+
+
+When a web app makes an RPC to a device using the Vanadium JavaScript library,
+a message is sent to the content script, which then forwards that message to
+the JavaScript running in the background page, and from there the message is
+sent to the NaCl plugin. The NaCl plugin handles incoming messages from
+JavaScript by calling Vanadium library code, written in Go.
+
+The NaCl plugin makes Vanadium RPCs to other Vanadium devices using WebSockets,
+which are a supported transport protocol of the Vanadium RPC protocol. Within
+the NaCl plugin, each web app origin is associated with a unique [Vanadium
+blessing][blessing], and RPCs are performed with the blessing associated with
+the origin of the web app making the request.
+
+The plugin sends messages back to web apps using the same message-passing
+system, but in reverse: a message is first sent from NaCl to the background
+page JavaScript, then to the content script running on the same tab as the web
+app, and finally to the web app.
+
+[background page]: https://developer.chrome.com/extensions/background_pages "Background Pages"
+[blessing]: ../glossary.md#blessing
+[content script]: https://developer.chrome.com/extensions/content_scripts "Content Scripts"
+[Go]: http://golang.org/ "The Go Programming Language"
+[Native Client]: https://developer.chrome.com/native-client "Native Client"
+[Pepper API]: https://developer.chrome.com/native-client/c-api "Pepper API"
+[Vanadium Chrome extension]: https://chrome.google.com/webstore/detail/jcaelnibllfoobpedofhlaobfcoknpap "Vanadium Chrome extension"
+[Vanadium JavaScript library]: https://github.com/vanadium/js "Vanadium JavaScript"
diff --git a/tos.md b/tos.md
new file mode 100644
index 0000000..2eb0c67
--- /dev/null
+++ b/tos.md
@@ -0,0 +1,11 @@
+# Terms of Service
+
+The Vanadium website (the "Website") and [Vanadium Cloud Services] (the
+"Services") are hosted by Google. By using and/or visiting the Website and/or
+Services, you consent to be bound by Google's general [Terms of Service], the
+[Google APIs Terms of Service], and Google's general [Privacy Policy].
+
+[Google APIs Terms of Service]: https://developers.google.com/terms/
+[Terms of Service]: https://www.google.com/intl/en/policies/terms/
+[Privacy Policy]: https://www.google.com/intl/en/policies/privacy/
+[Vanadium Cloud Services]: tools/services.md
