Original UJ/0.1 protocol spec; provided for historic reference

See our website repo for full history of the unhosted.org website.

Unhosted

Freedom from web 2.0's monopoly platforms

Unhosted is a project for strengthening free software against hosted software. With our protocol, a website is only source code. Dynamic data is encrypted and decentralised, to per-user storage nodes. This benefits free software, as well as scalability, robustness, and online privacy.

Download the code at gitHub Read the manifesto

UJ/0.1

UJ/0.1, or UJ/0.1-over-PubSign, is a protocol in which an unhosted web app that is running in a browser, makes an AJAX call to a storage node, to which the storage nodes responds. The call is made to the root of the domain, with the HTTP POST method.



PubSign-compatible command POST content:

Although at some point we will probably change to the MagicEnvelope that Salmon uses, version 0.1 uses "PubSign" to sign things you publish. There are four commands, two of which follow the PubSign convention, which is as follows:
  • "protocol": <name of the specific PubSign-compatible protocol>
  • "cmd": <whatever it is you want to publish - should adhere to protocol chosen above>
  • "PubSign": <raw hex RSA-signature signing the content of "cmd" above>
  • <other field/value pairs allowed by specific protocol...>

The content of the POST must be exactly one of the following four possible commands (valid responses are below each one):



SET command POST content:

  • "protocol": "UJ/0.1"
  • "cmd": <a JSON string, which decodes to:>
    • "method": "SET"
    • "chan": <the channel, so for '[email protected]', chan='test'>
    • "keyPath": <an ascii name for the key in the key-value store>
    • "value": <the value you want to store, can be any JSON object>
  • "WriteCaps": <password for writing/receiving this chan on this storage node>
  • "PubSign": <raw hex RSA-signature signing the content of "cmd" above>
Response: "OK" or "ERROR:" followed by some error message in English



GET command POST content:

  • "protocol": "UJ/0.1"
  • "cmd": <a JSON string, which decodes to:>
    • "method": "GET"
    • "chan": <the channel, so for '[email protected]', chan='test'>
    • "keyPath": <an ascii name for the key in the key-value store>
Response: the JSON that was in the "value" field of the last SET command for that chan and keyPath, or "ERROR:" followed by some error message in English



SEND command POST content:

  • "protocol": "UJ/0.1"
  • "cmd": <a JSON string, which decodes to:>
    • "method": "SEND"
    • "chan": <the channel, so for '[email protected]', chan='test'>
    • "keyPath": <an ascii name for a mailfolder within the chan's message store>
    • "value": <the body of the message, encrypted to the chan's public key>
  • "PubSign": <raw hex RSA-signature signing the content of "cmd" above>
Response: "OK" or "ERROR:" followed by some error message in English



RECEIVE command POST content:

  • "protocol": "UJ/0.1"
  • "cmd": <a JSON string, which decodes to:>
    • "method": "RECEIVE"
    • "chan": <the channel, so for '[email protected]', chan='test'>
    • "keyPath": <an ascii name for the key in the key-value store>
    • "delete": <boolean indicating whether to delete or leave on server>
  • "WriteCaps": <password for writing/receiving this chan on this storage node>
Response: an array of messages, or an empty array, or "ERROR:" followed by some error message in English



Additionally, the storage node should:

  • respond with correct CORS headers, in response to both HTTP POST and HTTP OPTIONS.
  • check the HTTP referer that the browser sent, and make sure it keeps all data of one referer completely separate from the data of another.
If any of this is unclear or ambiguous, then check the reference implementation at: https://github.com/michiel-unhosted/unhosted/tree/v0.1
This protocol is part of the alpha-release of the Unhosted project. It is likely to be changed to the next version before Unhosted reaches beta. For instance, the storage node could easily take advantage of the presence of PubSign signatures, and then we could get rid of the WriteCaps. Also, it has been suggested we should do at least the GET command with an HTTP GET method and not an HTTP POST.

[back]