UNHOSTED

The Unhosted WebDAV Standard

v0.1.10

Introduction

An Unhosted WebDAV service acts as an always-on data storage for its users. It does not host any application source code, nor does it execute any processing. To make use of an Unhosted WebDAV account, the user visits unhosted web apps that run in a browser, or user-agent. This user-agent discovers the user's Unhosted WebDAV service through WebFinger. It then redirects the user to an OAuth dialogue, to establish authentication. Finally, it uses WebDAV to read and write the data on the Unhosted WebDAV account.

This document is meant for implementers of an Unhosted WebDAV service. It descibes how an Unhosted WebDAV service should behave. Developers of unhosted web apps should download the SDK instead. End-users who are interested in understanding the concepts behind the unhosted web, are better off reading this interview. In any case, follow our mailing list for all the latest updates.

In order for your service to comply with the Unhosted WebDAV standard, it needs to implement WebFinger, OAuth2-cs, WebDAV, Http Basic auth, and CORS. All of these technologies should be configured to work together in the way that this specification describes using the keywords "MUST", "SHOULD" and "SHOULD EITHER .. OR", in the meaning specified by rcf2119.

Throughout this text, we use several variables, which are written in capitals, and with a $-sign in front of them. They describe the interaction between a user, this user's Unhosted WebDAV service (aka her unhosted account), and an application. The variables are:

WebFinger

The Unhosted WebDAV service MUST implement WebFinger and with XRD formatting. In the WebFinger data for $USERNAME @ $USERDOMAIN, it should announce an https-based $DAVURL with rel-attribute 'http://unhosted.org/spec/dav/0.1' . All WebFinger-related resources SHOULD be served over https and MUST be served with CORS headers that allow their retrieval from any origin.

OAuth2-cs

Given the $DAVURL announced via WebFinger, the Unhosted WebDAV implementer MUST make OAuth2-cs available on $DAVURL/oauth2/auth (no need for CORS headers here, because OAuth does redirection and not AJAX).

WebDAV

Whenever a user $USERNAME @ $USERDOMAIN grants an $APP access to a $RESOURCE, the Unhosted WebDAV implementer MUST make a WebDAV server available on $DAVURL/webdav/$USERDOMAIN/$USERNAME/$RESOURCE/, with CORS headers that allow access from whichever $APP sends it valid credentials.

Non-normative hint: For this, it is necessary to exclude (apart from the HEAD and GET verbs) the OPTIONS verb from the http basic auth restrictions. It is also necessary to set the -Allow-Credentials header to true, and to echo the Origin specified in the request headers back in the -Allow-Origin header (setting it to '*' works for the Webfinger URL, but not here, because of an extra restriction on CORS that applies when there are credentials involved). An example of how to configure this in apache's mod_dav can be found here.

Http basic auth

Whenever a user, who is successfully identified as $USERNAME @ $USERDOMAIN by the OAuth2-cs authentication server, and has successfully granted application $APP access to resource $RESOURCE, the OAuth access token given out to the $APP MUST be a valid http basic auth password for $DAVURL/webdav/$USERDOMAIN/$USERNAME/$RESOURCE/, when combined with the concatenation of $USERNAME, '@', and $USERDOMAIN as the http basic auth username. Http basic auth MUST be required for all verbs except OPTIONS, HEAD and GET. This means all content on the DAV server will be read/write-able for $USERNAME @ $USERDOMAIN, and world-readable. It is the responsibility of the application to add a payload encryption layer on top of this (end-to-end encryption).

Registration

In addition to the 'lrdd' entry that is needed in https://$USERDOMAIN/.well-known/host-meta as part of WebFinger, the implementer of Unhosted WebDAV SHOULD also add a 'register' entry. It should contain a template with two variables: {uri} and {redirect_url}. It SHOULD then also offer a human-readable web page with registration information on the URL that is constructed by filling in the concatenation of 'acct:', $USERNAME, '@', and $USERDOMAIN for the {uri} variable, and a redirect URL for the {redirect_url} variable. This registration page SHOULD EITHER allow the user to register a new unhosted account identified by $USERNAME @ $USERDOMAIN, OR provide human-readable information about why this is not being offered (for instance, if the username is taken, or if the server is not currently accepting registrations, or if some out-of-band actions are needed, like "if you are an ACME employee, but haven't received the credentials for your unhosted account yet, then please contact the helpdesk on [email protected]"). Whether registration as a new user is successful or not, upon completion the user-agent SHOULD be redirected back to the url that was filled in as the {redirect-url} in the template.

Conclusion

A non-normative example implementation of this specification is currently visible by visiting the world's first unhosted web app, on myfavouritesandwich.org, or viewing its javascript, and here is a stripped down representation of the http trace it produces. It is up to the application, and beyond the scope of this spec, to implement end-to-end encryption on top of this, possibly using the Stanford Javascript Crypto Library, possibly in a WebWorker process. This text may be changed for clarity - its history is tracked here. However, the standard it describes was frozen on 5 April 2011. The standard will not change for at least 6 months (until at least 5 October 2011). Even then, if at any point after that improvements to this standard are deemed desirable, every attempt will be made to make those changes non-breaking. We will follow semantic versioning.