ident

16.0 KB

1. // apps.hl — APPS AND THE LOGIN BUTTON (piece 2 of 6, ticket #25; CONCEPT.md "Apps",
2. // "One id per app", "Flow 1: login button"). Statics only, the server realm.
3. //
4. // appsTable pk @id index @owner, !apiKey
5. // { owner (account @id), name, origins ('a b c': the origins it runs
6. // on, space separated), apiKey, secretHash = sha256(secret), created, updated }
7. // connectionsTable pk @id index !pair, @app
8. // { pair = '<app @id>:<identity @id>', app, identity, created } — `created` is
9. // when the identity registered in that app (the per-app page).
10. // What an app holds is the identity's ONE SHORT ID (ident#23, store.hl
11. // `shortId`), the same in every app. Rows made before ident#23 still carry
12. // `appIdentity` (the old per-app id, 32 hex) until the app has migrated:
13. // POST /api/migrate-ids answers old → short and, with finish, drops them.
14. // requestsTable pk @id index !rid a login button press waiting for the choice:
15. // { rid, app (app @id), returnUrl, expires, invite (invite @id, ident#22; absent for a plain login) }
16. // grantsTable pk @id index !hash a one-time code on its way back to the app:
17. // { hash = sha256(code), app, identity, expires }
18. //
19. // Any signed-in account registers apps. An app has a PUBLIC API key (`pk_…`, it may sit
20. // in a page) and a SECRET (`sk_…`, the app's server only). The secret is shown ONCE, when
21. // it is made (register / new secret); only its sha256 is stored.
22. // Public app ids are the records' mpackdb UUIDs (`@id`), as for accounts and identities;
23. // the files live in storage/mpackdb/ (store.hl `dir`).
24. import { MPackDB } from 'hl:mpackdb'
25. import { now } from 'hl:time'
26. import { randomBytes, sha256 } from 'hl:crypto'
27. import { dir, envNumber, countOf, first, merged, hasControl, ownIdentity, isId, oldestFirst, identitiesTable, identityByShortId } from './store.hl'
29. static appsTable = new MPackDB(file = dir + '/apps.db', primaryKey = '@id', indexes = ['@owner' '!apiKey'])
30. static connectionsTable = new MPackDB(file = dir + '/connections.db', primaryKey = '@id', indexes = ['!pair' '@app'])
31. static requestsTable = new MPackDB(file = dir + '/requests.db', primaryKey = '@id', indexes = ['!rid'])
32. static grantsTable = new MPackDB(file = dir + '/grants.db', primaryKey = '@id', indexes = ['!hash'])
33. // INVITES (ident#22, invites.hl owns the rules; the table is here so deleting an app can drop its invites)
34. static invitesTable = new MPackDB(file = dir + '/invites.db', primaryKey = '@id', indexes = ['@app' '!hash'])
36. static grantTtl = envNumber('IDENT_GRANT_TTL_MS', 60000) // a one-time code: 60 s
37. static requestTtl = 1800000 // a login button press: 30 min
38. static maxOrigins = 10
39. static maxName = 60
41. // ---- validation -----------------------------------------------------------------------
42. static isList = (v) => { return v != null && hlTypeName(v) == 'Hybrid' && v.length != null }
43. static isObject = (v) => { return v != null && hlTypeName(v) == 'Hybrid' && v.length == null }
45. static checkName = (name) => {
46. if (name == null || hlTypeName(name) != 'String') { return { error = 'field name must be a string' field = 'name' } }
47. let t = name.trim()
48. if (t == '') { return { error = 'the app needs a name' field = 'name' } }
49. if (t.length > maxName) { return { error = 'field name is longer than ' + maxName + ' characters' field = 'name' } }
50. if (hasControl(t)) { return { error = 'field name contains a control character' field = 'name' } }
51. return { name = t }
52. }
54. // AN ORIGIN is `http(s)://host[:port]`: lowercase, no path, no user, no query. One
55. // trailing slash is forgiven. Answers { origin } or { error }.
56. static hostChars = 'abcdefghijklmnopqrstuvwxyz0123456789.-[]:'
57. static checkOrigin = (o) => {
58. if (o == null || hlTypeName(o) != 'String') { return { error = 'an origin must be a string' } }
59. let t = o.trim().toLowerCase()
60. if (t.length > 0 && t[t.length - 1] == '/') { t = t.slice(0, t.length - 1) }
61. if (t.length > 200) { return { error = 'the origin ' + t + ' is too long' } }
62. let scheme = t.slice(0, 7) == 'http://' ? 'http://' : (t.slice(0, 8) == 'https://' ? 'https://' : null)
63. if (scheme == null) { return { error = 'an origin starts with http:// or https:// (' + t + ')' } }
64. let host = t.slice(scheme.length, t.length)
65. if (host == '' || host[0] == '.' || host[0] == ':') { return { error = 'the origin ' + t + ' has no host' } }
66. let i = 0
67. while (i < host.length) {
68. if (!hostChars.includes(host[i])) { return { error = 'an origin is only scheme://host[:port], no path (' + t + ')' } }
69. i = i + 1
70. }
71. return { origin = t }
72. }
74. // the app form's input, STRICT: exactly { name, origins } — origins a list of 1-10
75. // strings. Answers { error, field } or { name, origins (list, deduplicated) }.
76. static appFields = ['name' 'origins']
77. static checkAppInput = (input) => {
78. if (!isObject(input)) { return { error = 'the app must be an object' field = '' } }
79. for (k of input.keys()) {
80. if (!appFields.includes(k)) { return { error = 'unknown field: ' + k field = k } }
81. }
82. for (k of appFields) {
83. if (input[k] == null) { return { error = 'missing field: ' + k field = k } }
84. }
85. let n = checkName(input.name)
86. if (n.error != null) { return n }
87. if (!isList(input.origins)) { return { error = 'field origins must be a list of strings' field = 'origins' } }
88. let out = []
89. for (o of input.origins) {
90. let c = checkOrigin(o)
91. if (c.error != null) { return { error = c.error field = 'origins' } }
92. if (!out.includes(c.origin)) { out.push(c.origin) }
93. }
94. if (out.length == 0) { return { error = 'give at least one origin the app runs on' field = 'origins' } }
95. if (out.length > maxOrigins) { return { error = 'at most ' + maxOrigins + ' origins' field = 'origins' } }
96. return { name = n.name origins = out }
97. }
99. // ---- apps -----------------------------------------------------------------------------
100. static newKey = () => { return 'pk_' + randomBytes(16) } // 32 hex
101. static newSecret = () => { return 'sk_' + randomBytes(24) } // 48 hex
102. static originsOf = (rec) => { return rec.origins == '' ? [] : rec.origins.split(' ') }
104. static appRowOf = (rec) => {
105. if (rec == null) { return null }
106. let origins = originsOf(rec)
107. return { id = rec.id name = rec.name origins = origins originsText = origins.join(' ') apiKey = rec.apiKey }
108. }
110. // the account's apps, oldest first (stored `created`, never key order)
111. static appRows = (accountId) => {
112. let out = []
113. if (!isId(accountId)) { return out }
114. for (r of oldestFirst(appsTable.find('owner', accountId))) { out.push(appRowOf(r)) }
115. return out
116. }
118. // the app record `id` (public) if the account owns it, else null
119. static ownApp = (accountId, id) => {
120. if (!isId(id)) { return null }
121. let r = appsTable.fetch(id)
122. if (r == null || r.owner != accountId) { return null }
123. return r
124. }
126. static appByKey = (key) => {
127. if (key == null || hlTypeName(key) != 'String' || key == '') { return null }
128. return first(appsTable.find('apiKey', key))
129. }
131. // answers { error, field } or { app (row), secret } — the secret leaves ident only here
132. static createApp = (accountId, input) => {
133. let c = checkAppInput(input)
134. if (c.error != null) { return c }
135. let secret = newSecret()
136. let id = appsTable.put({ owner = accountId name = c.name origins = c.origins.join(' ') apiKey = newKey() secretHash = sha256(secret) created = now() updated = now() })
137. return { app = appRowOf(appsTable.fetch(id)) secret = secret }
138. }
140. static updateApp = (accountId, id, input) => {
141. let r = ownApp(accountId, id)
142. if (r == null) { return { error = 'no such app' field = 'id' } }
143. let c = checkAppInput(input)
144. if (c.error != null) { return c }
145. appsTable.update(r.id, merged(r, { name = c.name origins = c.origins.join(' ') updated = now() }))
146. return { app = appRowOf(appsTable.fetch(r.id)) }
147. }
149. // a NEW SECRET: the old one stops working at once; the API key stays
150. static regenerateSecret = (accountId, id) => {
151. let r = ownApp(accountId, id)
152. if (r == null) { return { error = 'no such app' } }
153. let secret = newSecret()
154. appsTable.update(r.id, merged(r, { secretHash = sha256(secret) updated = now() }))
155. return { app = appRowOf(appsTable.fetch(r.id)) secret = secret }
156. }
158. // DELETING AN APP removes its connections (the per-app ids) with it; a pending login
159. // request or code for it dies because its app is gone
160. static deleteApp = (accountId, id) => {
161. let r = ownApp(accountId, id)
162. if (r == null) { return { error = 'no such app' } }
163. let conns = connectionsTable.find('app', id)
164. if (countOf(conns) > 0) { for (c of conns) { connectionsTable.delete(c.id) } }
165. let invs = invitesTable.find('app', id)
166. if (countOf(invs) > 0) { for (v of invs) { invitesTable.delete(v.id) } }
167. appsTable.delete(r.id)
168. return { deleted = id }
169. }
171. // ---- the login button ---------------------------------------------------------------
172. // A RETURN URL is absolute http(s), printable, no fragment, at most 2000 chars, and its
173. // origin is one of the app's. Answers { error } or { origin }.
174. static urlChars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._~:/?&=%+,;@!$()*[]'
175. static checkReturn = (url, appRec) => {
176. if (url == null || url == '') { return { error = 'the return parameter is missing' } }
177. if (url.length > 2000) { return { error = 'the return URL is too long' } }
178. let i = 0
179. while (i < url.length) {
180. if (!urlChars.includes(url[i])) { return { error = 'the return URL contains a character that is not allowed' } }
181. i = i + 1
182. }
183. let lower = url.toLowerCase()
184. let scheme = lower.slice(0, 7) == 'http://' ? 'http://' : (lower.slice(0, 8) == 'https://' ? 'https://' : null)
185. if (scheme == null) { return { error = 'the return URL must start with http:// or https://' } }
186. let rest = lower.slice(scheme.length, lower.length)
187. let end = rest.length
188. for (ch of ['/' '?']) {
189. let at = rest.indexOf(ch)
190. if (at >= 0 && at < end) { end = at }
191. }
192. let host = rest.slice(0, end)
193. if (host == '') { return { error = 'the return URL has no host' } }
194. let origin = scheme + host
195. if (!originsOf(appRec).includes(origin)) { return { error = 'the return URL is on ' + origin + ', which is not one of the origins registered for ' + appRec.name } }
196. return { origin = origin }
197. }
199. // the login button's GET /login?key=&return= : answers { error } or { rid }
200. static openRequest = (key, returnUrl) => {
201. let a = appByKey(key)
202. if (a == null) { return { error = key == null || key == '' ? 'the key parameter (the app’s API key) is missing' : 'no app has this API key' } }
203. let r = checkReturn(returnUrl, a)
204. if (r.error != null) { return r }
205. let rid = randomBytes(16)
206. requestsTable.put({ rid = rid app = a.id returnUrl = returnUrl expires = now() + requestTtl })
207. return { rid = rid }
208. }
210. // { rid, app (row), origin, returnUrl } or null (unknown, expired, or its app is gone)
211. static requestOf = (rid) => {
212. if (rid == null || hlTypeName(rid) != 'String' || rid == '') { return null }
213. let r = first(requestsTable.find('rid', rid))
214. if (r == null) { return null }
215. if (r.expires < now()) {
216. requestsTable.delete(r.id)
217. return null
218. }
219. let a = isId(r.app) ? appsTable.fetch(r.app) : null
220. if (a == null) { return null }
221. let c = checkReturn(r.returnUrl, a)
222. if (c.error != null) { return null } // the origin was removed from the app since
223. return { rid = r.rid app = appRowOf(a) origin = c.origin returnUrl = r.returnUrl invite = r.invite == null ? '' : r.invite }
224. }
226. // The identity's connection to the app, made on the first login
227. static connectionOf = (appId, identityId) => {
228. let pair = appId + ':' + identityId
229. let c = first(connectionsTable.find('pair', pair))
230. if (c != null) { return c }
231. let id = connectionsTable.put({ pair = pair app = appId identity = identityId created = now() })
232. return connectionsTable.fetch(id)
233. }
235. // "SIGN OUT" OF AN APP (ticket #2): forgets this identity's connection to it (its
236. // notification settings for the app). The identity's short id does not change: a later
237. // login makes a fresh connection and the app gets the same id. Notifications already sent
238. // through the old connection stay (as for a deleted app).
239. static disconnectConnection = (accountId, id) => {
240. if (!isId(id)) { return { error = 'no such app connection' } }
241. let c = connectionsTable.fetch(id)
242. if (c == null) { return { error = 'no such app connection' } }
243. let ident = ownIdentity(accountId, c.identity)
244. if (ident == null) { return { error = 'no such app connection' } }
245. connectionsTable.delete(c.id)
246. return { disconnected = id }
247. }
249. // A ONE-TIME CODE for app `appId` and identity `identityId` (public ids): 48 hex, single
250. // use, grantTtl (60 s), this app only. The login button AND the selector (selector.hl)
251. // hand out these codes; the app's server trades one with `exchange` below.
252. static issueCode = (appId, identityId) => {
253. connectionOf(appId, identityId)
254. let code = randomBytes(24)
255. grantsTable.put({ hash = sha256(code) app = appId identity = identityId expires = now() + grantTtl })
256. return code
257. }
259. // THE CHOICE: the account picks one of its identities for the request. Answers { error }
260. // or { url } — the app's return URL with a fresh one-time `ident_code`.
261. static grantLogin = (accountId, rid, identityId) => {
262. let rq = requestOf(rid)
263. if (rq == null) { return { error = 'this login request is unknown or expired — go back to the app and start again' } }
264. let ident = ownIdentity(accountId, identityId)
265. if (ident == null) { return { error = 'no such identity' } }
266. let code = issueCode(rq.app.id, identityId)
267. let r = first(requestsTable.find('rid', rid))
268. if (r != null) { requestsTable.delete(r.id) }
269. let sep = rq.returnUrl.includes('?') ? '&' : '?'
270. return { url = rq.returnUrl + sep + 'ident_code=' + code }
271. }
273. // THE EXCHANGE (the app's server): answers { status, error } or { identity }. The app
274. // authenticates with key + secret (401); a code works once, for its own app, for 60 s (400).
275. // A code shown to the wrong app is spent: it has leaked.
276. static exchange = (key, secret, code) => {
277. let a = appByKey(key)
278. if (a == null || sha256(secret) != a.secretHash) { return { status = 401 error = 'unknown API key or wrong secret' } }
279. let g = first(grantsTable.find('hash', sha256(code)))
280. if (g == null) { return { status = 400 error = 'unknown or already used code' } }
281. grantsTable.delete(g.id)
282. if (g.app != a.id) { return { status = 400 error = 'this code was not issued to this app' } }
283. if (g.expires < now()) { return { status = 400 error = 'the code expired' } }
284. let c = first(connectionsTable.find('pair', a.id + ':' + g.identity))
285. let ident = isId(g.identity) ? identitiesTable.fetch(g.identity) : null
286. if (c == null || ident == null) { return { status = 400 error = 'the identity is no longer connected to this app' } }
287. return { identity = ident.shortId }
288. }
290. // WHAT THE APP MEANT BY AN ID (ident#23): a notification or a lookup may name an identity by
291. // its short id, or — until the app has migrated — by its old per-app id. Answers the
292. // connection (of app `appId`) or null.
293. static connectionByAnyId = (appId, given) => {
294. let ident = identityByShortId(given)
295. if (ident != null) { return first(connectionsTable.find('pair', appId + ':' + ident.id)) }
296. if (given == null || hlTypeName(given) != 'String') { return null }
297. let rows = connectionsTable.find('app', appId)
298. if (countOf(rows) > 0) {
299. for (c of rows) { if (c.appIdentity != null && c.appIdentity == given) { return c } }
300. }
301. return null
302. }
304. // THE MIGRATION (ident#23), for the app's server: answers { ids } — every old per-app id
305. // → the identity's short id (an identity that was deleted has none and is left out).
306. // With `finish` the old ids are dropped afterwards: the app has stored the short ids.
307. static migrateIds = (a, finish) => {
308. let ids = {}
309. let n = 0
310. let rows = connectionsTable.find('app', a.id)
311. if (countOf(rows) > 0) {
312. for (c of rows) {
313. if (c.appIdentity == null) { continue }
314. let ident = isId(c.identity) ? identitiesTable.fetch(c.identity) : null
315. if (ident != null) { ids[c.appIdentity] = ident.shortId n = n + 1 }
316. if (finish) {
317. let rec = {}
318. for (k of c.keys()) { if (k != 'appIdentity') { rec[k] = c[k] } }
319. connectionsTable.update(c.id, rec)
320. }
321. }
322. }
323. return { ids = ids count = n finished = finish }
324. }