tickets

10.8 KB

1. // lib/connections.hl — AN APP IS CONNECTED TO ONE PROJECT (ticket tickets.worldapi.org#21; first app: gitoria).
2. // Statics only. One hl:mpackdb table beside the others (storage/mpackdb/connections.db, UUID keys):
3. //
4. // connectionsTable pk @id index nonce, hash, codeHash, project
5. // { status, nonce, app, label, returnUrl, state, project, createdBy, codeHash, expires, hash, created }
6. //
7. // THE FLOW (README "Connecting an app"):
8. // 1. the app sends the browser to <tickets>/connect?app=gitoria&label=<owner/repo>&return=<url>&state=<opaque>
9. // → a REQUEST (status 'request', an unguessable nonce) and a redirect to /connect/<nonce> (components/connect.hl).
10. // 2. the person logs in (ident), picks a project they are ADMIN of — or makes a new one — and confirms.
11. // The request becomes a connection (status 'waiting') with a ONE-TIME CODE (5 minutes); the page links back to
12. // `return?code=<code>&state=<state>`.
13. // 3. the app exchanges the code on the server: POST /api/connect/exchange { code } → { key, project }.
14. // The connection is 'active'; only the sha256 of the key is stored (`tktc_` + 48 hex, shown once).
15. // 4. the key acts inside THAT ONE project only (lib/api-helpers.hl apiAuth / actorIn): create tickets, comment, change state.
16. // Every write names the person: header `X-Tickets-Identity: <ident public id>`; the person is a tickets user
17. // (they logged in here once and chose a name) and the project's ROLES apply to them as to a token.
18. // 5. the project page shows "connected to <app>: <label>"; an admin's "Disconnect" deletes the row — the key is dead at once.
19. // The return URL is the app's: only https on worldapi.org (and its subdomains) — or an origin listed in
20. // TICKETS_CONNECT_ORIGINS (comma separated, e.g. http://127.0.0.1:8700 for a dev copy). The page shows the host.
21. import { MPackDB } from 'hl:mpackdb'
22. import { now } from 'hl:time'
23. import { randomBytes, sha256 } from 'hl:crypto'
24. import { env } from 'hl:proc'
25. import { storageDir, first, countOf, isHex, plainError } from './util.hl'
26. import { isIdentId, userOfIdentity, nameOfUser, publicUrl } from './users.hl'
27. import { projectRecord, projectRecords, isAdminOf, createProject, userOk, notAdmin } from './projects.hl'
29. static connectionsTable = new MPackDB(file = storageDir + '/connections.db', primaryKey = '@id', indexes = ['nonce', 'hash', 'codeHash', 'project'])
31. static requestTtlMs = 3600000
32. static codeTtlMs = 300000
34. static extraOrigins = () => {
35. v = env('TICKETS_CONNECT_ORIGINS')
36. out = []
37. if (v == null || v.trim() == '') { return out }
38. for (o of v.split(',')) { if (o.trim() != '') { out.push(o.trim()) } }
39. return out
40. }
42. // the characters a return URL may hold: URL-safe, no spaces, no quotes, no '#' (the code goes in the query)
43. static urlChars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._~/?&=%+,;:@!$()*'
45. // the host (with port) of an absolute URL: everything between '://' and the next '/' or '?'
46. static authorityOf = (url) => {
47. at = url.indexOf('://')
48. if (at < 0) { return '' }
49. rest = url.slice(at + 3)
50. let end = rest.length
51. s = rest.indexOf('/')
52. if (s >= 0 && s < end) { end = s }
53. q = rest.indexOf('?')
54. if (q >= 0 && q < end) { end = q }
55. return rest.slice(0, end)
56. }
58. // null when the URL may be an app's return address, else the reason
59. static returnError = (url) => {
60. if (url == null || hlTypeName(url) != 'String' || url == '') { return 'the app sent no return address' }
61. if (url.length > 500) { return 'the return address is too long' }
62. let i = 0
63. while (i < url.length) {
64. if (!urlChars.includes(url[i])) { return 'the return address holds a character that is not allowed' }
65. i = i + 1
66. }
67. for (o of extraOrigins()) {
68. if (url == o || url.startsWith(o + '/') || url.startsWith(o + '?')) { return null }
69. }
70. if (!url.startsWith('https://')) { return 'the return address must be https on worldapi.org' }
71. host = authorityOf(url)
72. if (host == '' || host.includes('@') || host.includes(':')) { return 'the return address has an unusual host' }
73. if (host != 'worldapi.org' && !host.endsWith('.worldapi.org')) { return 'the return address must be on worldapi.org' }
74. return null
75. }
77. static hostOf = (url) => { return authorityOf(url) }
79. static sepOf = (url) => { return url.includes('?') ? '&' : '?' }
81. // ---- 1. the request ---------------------------------------------------------------------------
82. // answers { nonce } or { error }
83. static createRequest = (app, label, returnUrl, state) => {
84. a = app == null ? '' : ('' + app).trim()
85. if (a == '') { return { error = 'the app sent no name' } }
86. let bad = plainError(a, 60, 'the app name')
87. if (bad == null) { bad = plainError(label == null ? '' : label, 100, 'the label') }
88. if (bad == null) { bad = plainError(state == null ? '' : state, 200, 'the state') }
89. if (bad == null) { bad = returnError(returnUrl) }
90. if (bad != null) { return { error = bad } }
91. let nonce = randomBytes(16)
92. id = connectionsTable.put({ status = 'request' nonce = nonce app = a label = label == null ? '' : label.trim() returnUrl = returnUrl state = state == null ? '' : state project = '' createdBy = '' codeHash = '' hash = '' expires = now() + requestTtlMs created = now() })
93. if (id == null) { return { error = 'could not store the request: ' + connectionsTable.lastError() } }
94. return { nonce = nonce }
95. }
97. // the open request of a nonce, or null (unknown, used, expired)
98. static requestOf = (nonce) => {
99. if (!isHex(nonce, 64)) { return null }
100. c = first(connectionsTable.find('nonce', nonce))
101. if (c == null || c.status != 'request' || c.expires < now()) { return null }
102. return c
103. }
105. // what the connect page shows of a request
106. static requestView = (c) => {
107. return { app = c.app label = c.label hasLabel = c.label != '' host = hostOf(c.returnUrl) }
108. }
110. // the projects a user is an ADMIN of: [{ id, title, slug }]
111. static adminProjects = (user) => {
112. out = []
113. if (user == null) { return out }
114. for (p of projectRecords()) { if (isAdminOf(p.id, user)) { out.push({ id = p.id title = p.title slug = p.slug }) } }
115. return out
116. }
118. // ---- 2. the confirmation ----------------------------------------------------------------------
119. // `projectId` '' = make a new project titled `title` (the person becomes its admin). Answers { error, forbidden? } or
120. // { url (back to the app, with the one-time code), project (title), slug }
121. static confirmRequest = (nonce, user, projectId, title) => {
122. c = requestOf(nonce)
123. if (c == null) { return { error = 'this request is used up or expired — start again from the app' } }
124. if (!userOk(user)) { return { error = 'log in with ident and choose a display name first' } }
125. let p = null
126. if (projectId == null || projectId == '') {
127. r = createProject(user, title, '', '')
128. if (r.error != null) { return { error = r.error } }
129. p = projectRecord(r.project.id)
130. } else {
131. p = projectRecord('' + projectId)
132. if (p == null) { return { error = 'no such project' } }
133. if (!isAdminOf(p.id, user)) { return notAdmin }
134. }
135. // a second connection of the same app and label to the same project replaces the first: its key dies
136. for (o of connectionsOf(p.id, true)) { if (o.app == c.app && o.label == c.label && o.id != c.id) { connectionsTable.delete(o.id) } }
137. code = randomBytes(24)
138. c.status = 'waiting'
139. c.nonce = ''
140. c.project = p.id
141. c.createdBy = user.id
142. c.codeHash = sha256(code)
143. c.expires = now() + codeTtlMs
144. connectionsTable.update(c.id, c)
145. let url = c.returnUrl + sepOf(c.returnUrl) + 'code=' + code
146. if (c.state != '') { url = url + '&state=' + encodeURIComponent(c.state) }
147. return { url = url project = p.title slug = p.slug }
148. }
150. // ---- 3. the exchange --------------------------------------------------------------------------
151. // answers { key, project (slug), title, api } or { error }
152. static exchangeConnectCode = (code) => {
153. if (!isHex(code, 200)) { return { error = 'that is not a connection code' } }
154. c = first(connectionsTable.find('codeHash', sha256(code)))
155. if (c == null || c.status != 'waiting' || c.expires < now()) { return { error = 'unknown, used or expired code — connect again' } }
156. p = projectRecord(c.project)
157. if (p == null) { return { error = 'the project is gone' } }
158. let key = 'tktc_' + randomBytes(24)
159. c.status = 'active'
160. c.hash = sha256(key)
161. c.codeHash = ''
162. c.expires = 0
163. c.connected = now()
164. connectionsTable.update(c.id, c)
165. return { key = key project = p.slug title = p.title api = publicUrl + '/api/projects/' + p.slug }
166. }
168. // ---- 4. the key -------------------------------------------------------------------------------
169. static isKeyHeader = (header) => {
170. if (header == null || hlTypeName(header) != 'String') { return false }
171. h = header.trim()
172. return (h.startsWith('Bearer ') || h.startsWith('bearer ')) && h.slice(7).trim().startsWith('tktc_')
173. }
175. // `Authorization: Bearer tktc_…` → the ACTIVE connection, or null
176. static connectionOfKey = (header) => {
177. if (!isKeyHeader(header)) { return null }
178. key = header.trim().slice(7).trim()
179. if (key.length != 53) { return null }
180. c = first(connectionsTable.find('hash', sha256(key)))
181. if (c == null || c.status != 'active') { return null }
182. return c
183. }
185. // the person an app write names (`X-Tickets-Identity`): { user } or { error }
186. static personOf = (identity) => {
187. if (identity == null || hlTypeName(identity) != 'String' || !isIdentId(identity.trim())) {
188. return { error = 'a write through a connection names the person: header X-Tickets-Identity: <their ident id>' }
189. }
190. u = userOfIdentity(identity.trim())
191. if (u == null || u.name == '') { return { error = 'that person has not logged in to tickets yet — they log in once and choose a display name' } }
192. return { user = u }
193. }
195. // ---- 5. the project page ----------------------------------------------------------------------
196. // the connections of a project: [{ id, app, label, by, when }]; `all` = also the waiting ones
197. static connectionsOf = (projectId, all) => {
198. out = []
199. rows = connectionsTable.find('project', projectId)
200. if (countOf(rows) == 0) { return out }
201. for (c of rows) { if (all || c.status == 'active') { out.push(c) } }
202. return out
203. }
205. static connectionRows = (projectId) => {
206. out = []
207. for (c of connectionsOf(projectId, false)) {
208. out.push({ id = c.id app = c.app label = c.label hasLabel = c.label != '' by = nameOfUser(c.createdBy) text = c.app + (c.label != '' ? ': ' + c.label : '') })
209. }
210. return out
211. }
213. // an admin ends a connection; the key is dead at once. answers { connections } or { error, forbidden? }
214. static disconnect = (projectId, actor, connectionId) => {
215. p = projectRecord(projectId)
216. if (p == null) { return { error = 'no such project' } }
217. if (!userOk(actor)) { return { error = 'log in with ident and choose a display name first' } }
218. if (!isAdminOf(p.id, actor)) { return notAdmin }
219. if (connectionId == null || hlTypeName(connectionId) != 'String' || connectionId == '') { return { error = 'no such connection' } }
220. c = connectionsTable.fetch(connectionId)
221. if (c == null || c.project != p.id) { return { error = 'no such connection' } }
222. connectionsTable.delete(c.id)
223. return { connections = connectionRows(p.id) }
224. }