ident

7.5 KB

1. // lib/invites.hl — THE INVITE SERVICE (ticket ident#22). Statics only, the server realm.
2. // An app (key + secret) asks ident for an INVITE for its project and role and gets a link
3. // `<ident>/invite/<token>`. Whoever opens the link joins with ident: the login button's
4. // own flow (lib/apps.hl openInvite / grantInvite) — email → code if signed out, the identity choice if
5. // signed in — and ident sends the browser back to the app's `return` URL with `ident_code` (the identity)
6. // AND `invite=<invite id>`. The app's server then asks POST /api/invites/get which identity
7. // accepted the invite (compare it with the one the exchange gave). Concept: CONCEPT.md is
8. // silent on invites; the ticket is the spec.
9. // This file holds the invites table and every write to it; the checks: lib/invites-helpers.hl.
10. //
11. // invitesTable pk @id index @app, !hash
12. // { app (app @id), hash = sha256(token), project, role, returnUrl, uses, acceptedBy
13. // ('a b c': the identities' short ids that accepted it (invites accepted before ident#23 hold the old per-app id), space separated),
14. // expires, revoked (0 or the time), mailedAt (0 or the time), created }
15. //
16. // Single use by default (`uses`, up to 1000), 7 days by default (`days`, up to 90). The link
17. // (token) is shown once, in the answer of the create call; only its sha256 is stored.
18. // A state is one of: revoked, used (all uses taken), expired, open.
19. import { MPackDB } from 'hl:mpackdb'
20. import { now } from 'hl:time'
21. import { randomBytes, sha256 } from 'hl:crypto'
22. import { env } from 'hl:proc'
23. import { dir, envNumber, countOf, first, merged, validEmail, normEmail, isId, oldestFirst } from './util.hl'
24. import { checkReturn } from './apps-helpers.hl'
25. import { isWhole, checkText, acceptedList, usedCount, problemOf } from './invites-helpers.hl'
26. import { identitiesTable } from './identities.hl'
28. static invitesTable = new MPackDB(file = dir + '/invites.db', primaryKey = '@id', indexes = ['@app' '!hash'])
30. static dayMs = envNumber('IDENT_INVITE_DAY_MS', 86400000) // a day (the gate shortens it)
31. static defaultUses = 1
32. static maxUses = 1000
33. static defaultDays = 7
34. static maxDays = 90
35. // mails one app may send through ident per 24 h (an app must not turn ident into a mail cannon)
36. static mailLimit = envNumber('IDENT_INVITE_MAIL_LIMIT', 50)
37. static publicUrl = env('IDENT_PUBLIC_URL') != null && env('IDENT_PUBLIC_URL') != '' ? env('IDENT_PUBLIC_URL') : null
39. // ---- state ----------------------------------------------------------------------------
40. static stateOf = (rec) => {
41. if (rec.revoked != null && rec.revoked > 0) { return 'revoked' }
42. if (usedCount(rec) >= rec.uses) { return 'used' }
43. if (rec.expires < now()) { return 'expired' }
44. return 'open'
45. }
46. // what the app sees of an invite (never the token)
47. static inviteRow = (rec) => {
48. return { id = rec.id project = rec.project role = rec.role state = stateOf(rec) uses = rec.uses used = usedCount(rec) identities = acceptedList(rec) expires = rec.expires created = rec.created }
49. }
51. // ---- the app's calls -------------------------------------------------------------------
52. static mailedLately = (appId) => {
53. let n = 0
54. t0 = now() - dayMs
55. rows = invitesTable.find('app', appId)
56. if (countOf(rows) > 0) { for (r of rows) { if (r.mailedAt != null && r.mailedAt > t0) { n = n + 1 } } }
57. return n
58. }
60. // `base` is where the link points (the request's own origin when IDENT_PUBLIC_URL is unset).
61. // answers { status, error } or { invite (row), url, mail (null | { to, days }) } — the caller mails
62. static createInvite = (appRec, b, base) => {
63. p = checkText(b.project, 'project')
64. if (p.error != null) { return { status = 400 error = p.error } }
65. r = checkText(b.role, 'role')
66. if (r.error != null) { return { status = 400 error = r.error } }
67. rt = checkReturn(b['return'], appRec)
68. if (rt.error != null) { return { status = 400 error = rt.error } }
69. let uses = b.uses == null ? defaultUses : b.uses
70. if (!isWhole(uses) || uses < 1 || uses > maxUses) { return { status = 400 error = 'field uses must be a whole number from 1 to ' + maxUses } }
71. let days = b.days == null ? defaultDays : b.days
72. if (!isWhole(days) || days < 1 || days > maxDays) { return { status = 400 error = 'field days must be a whole number from 1 to ' + maxDays } }
73. let to = null
74. if (b.email != null) {
75. to = normEmail(b.email)
76. if (!validEmail(to)) { return { status = 400 error = 'field email is not an email address' } }
77. if (mailedLately(appRec.id) >= mailLimit) { return { status = 429 error = 'too many invitation mails from this app in 24 hours' } }
78. }
79. token = randomBytes(16)
80. t = now()
81. id = invitesTable.put({ app = appRec.id hash = sha256(token) project = p.text role = r.text returnUrl = b['return'] uses = uses acceptedBy = '' expires = t + days * dayMs revoked = 0 mailedAt = to != null ? t : 0 created = t })
82. return { invite = inviteRow(invitesTable.fetch(id)) url = base + '/invite/' + token mail = to != null ? { to = to days = days } : null }
83. }
85. // the invite `id` if the app owns it, else null
86. static ownInvite = (appRec, id) => {
87. if (!isId(id)) { return null }
88. r = invitesTable.fetch(id)
89. if (r == null || r.app != appRec.id) { return null }
90. return r
91. }
93. // all of the app's invites, oldest first; `project` (optional) narrows it
94. static listInvites = (appRec, project) => {
95. out = []
96. for (r of oldestFirst(invitesTable.find('app', appRec.id))) {
97. if (project == null || r.project == project) { out.push(inviteRow(r)) }
98. }
99. return out
100. }
102. // answers { status, error } or { invite (row) }
103. static revokeInvite = (appRec, id) => {
104. r = ownInvite(appRec, id)
105. if (r == null) { return { status = 404 error = 'no such invite' } }
106. s = stateOf(r)
107. if (s != 'open') { return { status = 409 error = 'the invite is not open (it is ' + s + ')' } }
108. invitesTable.update(r.id, merged(r, { revoked = now() }))
109. return { invite = inviteRow(invitesTable.fetch(r.id)) }
110. }
112. // DELETING AN APP (lib/apps.hl deleteApp) drops its invites with it
113. static dropInvitesOf = (appId) => {
114. invs = invitesTable.find('app', appId)
115. if (countOf(invs) > 0) { for (v of invs) { invitesTable.delete(v.id) } }
116. return null
117. }
119. // ---- the person's side (the login flow is lib/apps.hl openInvite / grantInvite) ---------------
120. // GET /invite/<token>: answers { status, title, error } (an error page) or { invite (record) } — one that can
121. // still be accepted
122. static openableInvite = (token) => {
123. rec = token == null || hlTypeName(token) != 'String' || token.length > 64 ? null : first(invitesTable.find('hash', sha256(token)))
124. if (rec == null) { return { status = 404 title = 'Unknown invitation' error = 'This invitation link is not valid. Check that you copied all of it, or ask whoever invited you for a new one.' } }
125. s = stateOf(rec)
126. if (s != 'open') { return { status = 410 title = s == 'used' ? 'Invitation already used' : (s == 'expired' ? 'Invitation expired' : 'Invitation withdrawn') error = problemOf(s) } }
127. return { invite = rec }
128. }
130. static inviteById = (id) => { return isId(id) ? invitesTable.fetch(id) : null }
132. // THE IDENTITY ACCEPTS the invite `rec` (its connection `conn` to the app is made already). Answers { error } or
133. // { ok }. An identity that already accepted this invite may pass again without taking another use.
134. static acceptInvite = (rec, identityId, conn) => {
135. list = acceptedList(rec)
136. s = stateOf(rec)
137. if (s == 'revoked') { return { error = problemOf(s) } }
138. mine = identitiesTable.fetch(identityId).shortId
139. if (!list.includes(mine) && !(conn.appIdentity != null && list.includes(conn.appIdentity))) {
140. if (s != 'open') { return { error = problemOf(s) } }
141. list.push(mine)
142. invitesTable.update(rec.id, merged(rec, { acceptedBy = list.join(' ') }))
143. }
144. return { ok = true }
145. }