Add proposals/0000-http-pinning-service-api.md

1 files changed, 205 insertions, 0 deletions

diff --git a/proposals/0000-http-pinning-service-api.md b/proposals/0000-http-pinning-service-api.md
new file mode 100644
index 0000000..9fdc5ac
--- /dev/null
+++ b/proposals/0000-http-pinning-service-api.md
@@ -0,0 +1,205 @@
+
+Title: **DEP-0000: HTTP Pinning Service API**
+
+Short Name: `0000-http-pinning-service-api`
+
+Type: Standard
+
+Status: Draft (as of 2018-03-31)
+
+Github PR: (add HTTPS link here after PR is opened)
+
+Authors: Paul Frazee
+
+
+# Summary [summary]: #summary
+
+An HTTP API for adding and removing Dat data.
+
+
+# Motivation [motivation]: #motivation
+
+Users frequently make use of "pinning services" to keep their Dat data online
+independently of their personal devices. By specifying a standard API for
+accessing pinning services, we can integrate interfaces for these services to
+Dat clients (including the Dat CLI and Beaker Browser). For example, in the Dat
+CLI, it will be possible to execute commands such as:
+
+```
+dat publish --name myarchive my-pinning-service.com
+```
+
+
+# Service description (PSA) document [service-description]: #service-description
+
+Servers should host the PSA service-description document at `/.well-known/psa`.
+It may be fetched using a GET request. This document will fit the following schema:
+
+```json
+{
+  "PSA": 1,
+  "title": "My Pinning Service",
+  "description": "Keep your Dats online!",
+  "links": [{
+    "rel": "user-accounts-api.com/v1",
+    "title": "User accounts API",
+    "href": "/v1/accounts"
+  }, {
+    "rel": "datprotocol.com/deps/0000-http-pinning-service-api",
+    "title": "Dat pinning API",
+    "href": "/v1/dats"
+  }]
+}
+```
+
+You can read more about the [PSA Service Discovery
+Protocol](https://github.com/beakerbrowser/beaker/wiki/PSA-Web-Service-Discovery-Protocol).
+
+The PSA document must provide links to two API resources: the User Accounts
+API, and the Dat Pinning API. These resources should be indicated by the
+`user-accounts-api.com/v1` and `datprotocol.com/deps/0000-http-pinning-service-api`
+rel-types, respectively. (These rel-types will need to be updated
+with the final URLs for their specifications.) If either API is absent from
+the PSA document, the service will be rejected.
+
+
+# User accounts API [user-accounts-api]: #user-accounts-api
+
+The user-accounts API should provide the following resources:
+
+```
+POST /register  Register a new account.
+POST /verify    Verify the email address of a recently-registered account.
+POST /login     Create a new session with an existing account.
+POST /logout    End a session.
+GET  /account   Get information about the account attached to the current session.
+POST /account   Update information about the account attached to the current session.
+```
+
+TODO- specify each route in detail.
+
+Full documentation for this API should be made available at https://user-accounts-api.com.
+
+## User registration flow [user-registration-flow]: #user-registration-flow
+
+### Step 1. Register
+
+User POSTS to `/register` with body:
+
+```json
+{
+  email: String
+  username: String
+  password: String
+}
+```
+
+Server creates a new account for the user. A random 32-byte email-verification
+nonce is created. The user record indicates:
+
+scopes|isEmailVerified|emailVerifyNonce
+------|---------------|----------------
+none|false|XXX
+
+Server sends an email to the user with the `emailVerifyNonce`. 
+
+Server responds 200 or 204.
+
+### Step 2. Verify (POST /verify)
+
+User POSTS `/v1/verify` with JSON body:
+
+```
+{
+  username: String, username of the account
+  nonce: String, verification nonce
+}
+```
+
+Server updates user record to indicate:
+
+scopes|isEmailVerified|emailVerifyNonce
+------|---------------|----------------
+user|true|null
+
+Sever generates a session and session token, and responds 200 with a JSON body:
+
+```json
+{
+  sessionToken: String, users session token
+}
+```
+
+## Session login flow [session-login-flow]: #session-login-flow
+
+User POSTS to `/login` with body:
+
+```json
+{
+  username: String
+  password: String
+}
+```
+
+Sever generates a session and session token, and responds 200 with a JSON body:
+
+```json
+{
+  sessionToken: String, users session token
+}
+```
+
+
+# Dat pinning API [dat-pinning-api]: #dat-pinning-api
+
+The dat pinning API should provide the following resources:
+
+```
+GET  /            List all Dat data pinned by this account.
+POST /add         Add a Dat to this account's list of pins.
+POST /remove      Remove a Dat from this account's list of pins.
+GET  /item/:key   Get information about a Dat in the account's list of pins.
+                  Key may be the pubkey or name of the dat.
+POST /item/:key   Update information about a Dat in the account's list of pins.
+                  Key may be the pubkey or name of the dat.
+```
+
+TODO- specify each route in detail.
+
+
+# Authentication [authentication]: #authentication
+
+Clients should use the [User accounts API](#user-accounts-api) to fetch a
+session token from the service. This token should be included in the
+`Authentication` header using the `Bearer` scheme.
+
+
+# Error responses [error-responses]: #error-responses
+
+All error responses should respond with a JSON body which matches the
+following schema:
+
+```json
+{
+  message: String
+}
+```
+
+The content of `message` will be displayed to the user. It should explain the
+error and, if appropriate, give steps for solving the issue. Other fields may
+be included in the response.
+
+
+# Rationale and alternatives [alternatives]: #alternatives
+
+- The motivations and drawbacks of the PSA Service Document are discussed
+[here](https://github.com/beakerbrowser/beaker/wiki/PSA-Web-Service-Discovery-Protocol#motivation).
+Without a description format, it becomes difficult to handle user
+authentication. We would probably need to use the HTTP Basic scheme and remove
+any mechanisms for registering new accounts.
+
+
+# Changelog [changelog]: #changelog
+
+- YYYY-MM-DD: First complete draft submitted for review
+