1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
|
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:
```
{
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:
```
{
sessionToken: String, users session token
}
```
## Session login flow [session-login-flow]: #session-login-flow
User POSTS to `/login` with body:
```
{
username: String
password: String
}
```
Sever generates a session and session token, and responds 200 with a JSON body:
```
{
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:
```
{
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
|
