tickets

10.9 KB

1. // 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 (project.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 { userDir, firstOf, countOfList, isHex, isIdentId, plainError, usersTable, nameOfUser, publicUrl } from './users.hl'
26. import { projectRecord, projectRecords, isAdminOf, createProject, userOk, notAdmin } from './store.hl'
28. static connectionsTable = new MPackDB(file = userDir + '/connections.db', primaryKey = '@id', indexes = ['nonce', 'hash', 'codeHash', 'project'])
30. static requestTtlMs = 3600000
31. static codeTtlMs = 300000
33. static extraOrigins = () => {
34. let v = env('TICKETS_CONNECT_ORIGINS')
35. let out = []
36. if (v == null || v.trim() == '') { return out }
37. for (o of v.split(',')) { if (o.trim() != '') { out.push(o.trim()) } }
38. return out
39. }
41. // the characters a return URL may hold: URL-safe, no spaces, no quotes, no '#' (the code goes in the query)
42. static urlChars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._~/?&=%+,;:@!$()*'
44. // the host (with port) of an absolute URL: everything between '://' and the next '/' or '?'
45. static authorityOf = (url) => {
46. let at = url.indexOf('://')
47. if (at < 0) { return '' }
48. let rest = url.slice(at + 3)
49. let end = rest.length
50. let s = rest.indexOf('/')
51. if (s >= 0 && s < end) { end = s }
52. let q = rest.indexOf('?')
53. if (q >= 0 && q < end) { end = q }
54. return rest.slice(0, end)
55. }
57. // null when the URL may be an app's return address, else the reason
58. static returnError = (url) => {
59. if (url == null || hlTypeName(url) != 'String' || url == '') { return 'the app sent no return address' }
60. if (url.length > 500) { return 'the return address is too long' }
61. let i = 0
62. while (i < url.length) {
63. if (!urlChars.includes(url[i])) { return 'the return address holds a character that is not allowed' }
64. i = i + 1
65. }
66. for (o of extraOrigins()) {
67. if (url == o || url.startsWith(o + '/') || url.startsWith(o + '?')) { return null }
68. }
69. if (!url.startsWith('https://')) { return 'the return address must be https on worldapi.org' }
70. let host = authorityOf(url)
71. if (host == '' || host.includes('@') || host.includes(':')) { return 'the return address has an unusual host' }
72. if (host != 'worldapi.org' && !host.endsWith('.worldapi.org')) { return 'the return address must be on worldapi.org' }
73. return null
74. }
76. static hostOf = (url) => { return authorityOf(url) }
78. static sepOf = (url) => { return url.includes('?') ? '&' : '?' }
80. // ---- 1. the request ---------------------------------------------------------------------------
81. // answers { nonce } or { error }
82. static createRequest = (app, label, returnUrl, state) => {
83. let a = app == null ? '' : ('' + app).trim()
84. if (a == '') { return { error = 'the app sent no name' } }
85. let bad = plainError(a, 60, 'the app name')
86. if (bad == null) { bad = plainError(label == null ? '' : label, 100, 'the label') }
87. if (bad == null) { bad = plainError(state == null ? '' : state, 200, 'the state') }
88. if (bad == null) { bad = returnError(returnUrl) }
89. if (bad != null) { return { error = bad } }
90. let nonce = randomBytes(16)
91. let 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() })
92. if (id == null) { return { error = 'could not store the request: ' + connectionsTable.lastError() } }
93. return { nonce = nonce }
94. }
96. // the open request of a nonce, or null (unknown, used, expired)
97. static requestOf = (nonce) => {
98. if (!isHex(nonce, 64)) { return null }
99. let c = firstOf(connectionsTable.find('nonce', nonce))
100. if (c == null || c.status != 'request' || c.expires < now()) { return null }
101. return c
102. }
104. // what the connect page shows of a request
105. static requestView = (c) => {
106. return { app = c.app label = c.label hasLabel = c.label != '' host = hostOf(c.returnUrl) }
107. }
109. // the projects a user is an ADMIN of: [{ id, title, slug }]
110. static adminProjects = (user) => {
111. let out = []
112. if (user == null) { return out }
113. for (p of projectRecords()) { if (isAdminOf(p.id, user)) { out.push({ id = p.id title = p.title slug = p.slug }) } }
114. return out
115. }
117. // ---- 2. the confirmation ----------------------------------------------------------------------
118. // `projectId` '' = make a new project titled `title` (the person becomes its admin). Answers { error, forbidden? } or
119. // { url (back to the app, with the one-time code), project (title), slug }
120. static confirmRequest = (nonce, user, projectId, title) => {
121. let c = requestOf(nonce)
122. if (c == null) { return { error = 'this request is used up or expired — start again from the app' } }
123. if (!userOk(user)) { return { error = 'log in with ident and choose a display name first' } }
124. let p = null
125. if (projectId == null || projectId == '') {
126. let r = createProject(user, title, '', '')
127. if (r.error != null) { return { error = r.error } }
128. p = projectRecord(r.project.id)
129. } else {
130. p = projectRecord('' + projectId)
131. if (p == null) { return { error = 'no such project' } }
132. if (!isAdminOf(p.id, user)) { return notAdmin }
133. }
134. // a second connection of the same app and label to the same project replaces the first: its key dies
135. for (o of connectionsOf(p.id, true)) { if (o.app == c.app && o.label == c.label && o.id != c.id) { connectionsTable.delete(o.id) } }
136. let code = randomBytes(24)
137. c.status = 'waiting'
138. c.nonce = ''
139. c.project = p.id
140. c.createdBy = user.id
141. c.codeHash = sha256(code)
142. c.expires = now() + codeTtlMs
143. connectionsTable.update(c.id, c)
144. let url = c.returnUrl + sepOf(c.returnUrl) + 'code=' + code
145. if (c.state != '') { url = url + '&state=' + encodeURIComponent(c.state) }
146. return { url = url project = p.title slug = p.slug }
147. }
149. // ---- 3. the exchange --------------------------------------------------------------------------
150. // answers { key, project (slug), title, api } or { error }
151. static exchangeConnectCode = (code) => {
152. if (!isHex(code, 200)) { return { error = 'that is not a connection code' } }
153. let c = firstOf(connectionsTable.find('codeHash', sha256(code)))
154. if (c == null || c.status != 'waiting' || c.expires < now()) { return { error = 'unknown, used or expired code — connect again' } }
155. let p = projectRecord(c.project)
156. if (p == null) { return { error = 'the project is gone' } }
157. let key = 'tktc_' + randomBytes(24)
158. c.status = 'active'
159. c.hash = sha256(key)
160. c.codeHash = ''
161. c.expires = 0
162. c.connected = now()
163. connectionsTable.update(c.id, c)
164. return { key = key project = p.slug title = p.title api = publicUrl + '/api/projects/' + p.slug }
165. }
167. // ---- 4. the key -------------------------------------------------------------------------------
168. static isKeyHeader = (header) => {
169. if (header == null || hlTypeName(header) != 'String') { return false }
170. let h = header.trim()
171. return (h.startsWith('Bearer ') || h.startsWith('bearer ')) && h.slice(7).trim().startsWith('tktc_')
172. }
174. // `Authorization: Bearer tktc_…` → the ACTIVE connection, or null
175. static connectionOfKey = (header) => {
176. if (!isKeyHeader(header)) { return null }
177. let key = header.trim().slice(7).trim()
178. if (key.length != 53) { return null }
179. let c = firstOf(connectionsTable.find('hash', sha256(key)))
180. if (c == null || c.status != 'active') { return null }
181. return c
182. }
184. // the person an app write names (`X-Tickets-Identity`): { user } or { error }
185. static personOf = (identity) => {
186. if (identity == null || hlTypeName(identity) != 'String' || !isIdentId(identity.trim())) {
187. return { error = 'a write through a connection names the person: header X-Tickets-Identity: <their ident id>' }
188. }
189. let u = firstOf(usersTable.find('identity', identity.trim()))
190. 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' } }
191. return { user = u }
192. }
194. // ---- 5. the project page ----------------------------------------------------------------------
195. // the connections of a project: [{ id, app, label, by, when }]; `all` = also the waiting ones
196. static connectionsOf = (projectId, all) => {
197. let out = []
198. let rows = connectionsTable.find('project', projectId)
199. if (countOfList(rows) == 0) { return out }
200. for (c of rows) { if (all || c.status == 'active') { out.push(c) } }
201. return out
202. }
204. static connectionRows = (projectId) => {
205. let out = []
206. for (c of connectionsOf(projectId, false)) {
207. 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 : '') })
208. }
209. return out
210. }
212. // an admin ends a connection; the key is dead at once. answers { connections } or { error, forbidden? }
213. static disconnect = (projectId, actor, connectionId) => {
214. let p = projectRecord(projectId)
215. if (p == null) { return { error = 'no such project' } }
216. if (!userOk(actor)) { return { error = 'log in with ident and choose a display name first' } }
217. if (!isAdminOf(p.id, actor)) { return notAdmin }
218. if (connectionId == null || hlTypeName(connectionId) != 'String' || connectionId == '') { return { error = 'no such connection' } }
219. let c = connectionsTable.fetch(connectionId)
220. if (c == null || c.project != p.id) { return { error = 'no such connection' } }
221. connectionsTable.delete(c.id)
222. return { connections = connectionRows(p.id) }
223. }