ident

9.0 KB

1. // 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 (apps.hl) — email → code if signed out, the identity choice if signed in — and
5. // 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. //
10. // invitesTable pk @id index @app, !hash (apps.hl)
11. // { app (app @id), hash = sha256(token), project, role, returnUrl, uses, acceptedBy
12. // ('a b c': the identities' short ids that accepted it (invites accepted before ident#23 hold the old per-app id), space separated),
13. // expires, revoked (0 or the time), mailedAt (0 or the time), created }
14. //
15. // Single use by default (`uses`, up to 1000), 7 days by default (`days`, up to 90). The link
16. // (token) is shown once, in the answer of the create call; only its sha256 is stored.
17. // A state is one of: revoked, used (all uses taken), expired, open.
18. import { now } from 'hl:time'
19. import { randomBytes, sha256 } from 'hl:crypto'
20. import { env } from 'hl:proc'
21. import { invitesTable, requestsTable, requestOf, requestTtl, checkReturn, originsOf, issueCode, connectionOf } from './apps.hl'
22. import { envNumber, countOf, first, merged, hasControl, validEmail, normEmail, isId, oldestFirst, ownIdentity, identitiesTable } from './store.hl'
24. static dayMs = envNumber('IDENT_INVITE_DAY_MS', 86400000) // a day (the gate shortens it)
25. static defaultUses = 1
26. static maxUses = 1000
27. static defaultDays = 7
28. static maxDays = 90
29. static maxText = 60
30. // mails one app may send through ident per 24 h (an app must not turn ident into a mail cannon)
31. static mailLimit = envNumber('IDENT_INVITE_MAIL_LIMIT', 50)
32. static publicUrl = env('IDENT_PUBLIC_URL') != null && env('IDENT_PUBLIC_URL') != '' ? env('IDENT_PUBLIC_URL') : null
34. static isWhole = (n) => { return hlTypeName(n) == 'Number' && !('' + n).includes('.') && !('' + n).includes('e') }
36. // ---- state ----------------------------------------------------------------------------
37. static acceptedList = (rec) => { return rec.acceptedBy == null || rec.acceptedBy == '' ? [] : rec.acceptedBy.split(' ') }
38. static usedCount = (rec) => { return acceptedList(rec).length }
39. static stateOf = (rec) => {
40. if (rec.revoked != null && rec.revoked > 0) { return 'revoked' }
41. if (usedCount(rec) >= rec.uses) { return 'used' }
42. if (rec.expires < now()) { return 'expired' }
43. return 'open'
44. }
45. // what the app sees of an invite (never the token)
46. static inviteRow = (rec) => {
47. 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 }
48. }
50. // the message of a state that cannot be accepted
51. static problemOf = (state) => {
52. if (state == 'used') { return 'This invitation was already used.' }
53. if (state == 'expired') { return 'This invitation has expired. Ask whoever invited you for a new one.' }
54. if (state == 'revoked') { return 'This invitation was withdrawn. Ask whoever invited you for a new one.' }
55. return ''
56. }
58. // ---- the app's calls -------------------------------------------------------------------
59. static checkText = (v, name) => {
60. if (v == null || hlTypeName(v) != 'String') { return { error = 'field ' + name + ' must be a string' } }
61. let t = v.trim()
62. if (t == '') { return { error = 'field ' + name + ' is empty' } }
63. if (t.length > maxText) { return { error = 'field ' + name + ' is longer than ' + maxText + ' characters' } }
64. if (hasControl(t)) { return { error = 'field ' + name + ' contains a control character' } }
65. return { text = t }
66. }
68. static mailedLately = (appId) => {
69. let n = 0
70. let t0 = now() - dayMs
71. let rows = invitesTable.find('app', appId)
72. if (countOf(rows) > 0) { for (r of rows) { if (r.mailedAt != null && r.mailedAt > t0) { n = n + 1 } } }
73. return n
74. }
76. // `base` is where the link points (the request's own origin when IDENT_PUBLIC_URL is unset).
77. // answers { status, error } or { invite (row), url, mail (null | { to, days }) } — the caller mails
78. static createInvite = (appRec, b, base) => {
79. let p = checkText(b.project, 'project')
80. if (p.error != null) { return { status = 400 error = p.error } }
81. let r = checkText(b.role, 'role')
82. if (r.error != null) { return { status = 400 error = r.error } }
83. let rt = checkReturn(b['return'], appRec)
84. if (rt.error != null) { return { status = 400 error = rt.error } }
85. let uses = b.uses == null ? defaultUses : b.uses
86. if (!isWhole(uses) || uses < 1 || uses > maxUses) { return { status = 400 error = 'field uses must be a whole number from 1 to ' + maxUses } }
87. let days = b.days == null ? defaultDays : b.days
88. if (!isWhole(days) || days < 1 || days > maxDays) { return { status = 400 error = 'field days must be a whole number from 1 to ' + maxDays } }
89. let to = null
90. if (b.email != null) {
91. to = normEmail(b.email)
92. if (!validEmail(to)) { return { status = 400 error = 'field email is not an email address' } }
93. if (mailedLately(appRec.id) >= mailLimit) { return { status = 429 error = 'too many invitation mails from this app in 24 hours' } }
94. }
95. let token = randomBytes(16)
96. let t = now()
97. let 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 })
98. return { invite = inviteRow(invitesTable.fetch(id)) url = base + '/invite/' + token mail = to != null ? { to = to days = days } : null }
99. }
101. // the invite `id` if the app owns it, else null
102. static ownInvite = (appRec, id) => {
103. if (!isId(id)) { return null }
104. let r = invitesTable.fetch(id)
105. if (r == null || r.app != appRec.id) { return null }
106. return r
107. }
109. // all of the app's invites, oldest first; `project` (optional) narrows it
110. static listInvites = (appRec, project) => {
111. let out = []
112. for (r of oldestFirst(invitesTable.find('app', appRec.id))) {
113. if (project == null || r.project == project) { out.push(inviteRow(r)) }
114. }
115. return out
116. }
118. // answers { status, error } or { invite (row) }
119. static revokeInvite = (appRec, id) => {
120. let r = ownInvite(appRec, id)
121. if (r == null) { return { status = 404 error = 'no such invite' } }
122. let s = stateOf(r)
123. if (s != 'open') { return { status = 409 error = 'the invite is not open (it is ' + s + ')' } }
124. invitesTable.update(r.id, merged(r, { revoked = now() }))
125. return { invite = inviteRow(invitesTable.fetch(r.id)) }
126. }
128. // ---- the person's side ------------------------------------------------------------------
129. // GET /invite/<token>: answers { status, title, error } (an error page) or { rid } — a login
130. // request of the app (apps.hl) that carries the invite, so the login flow does the rest.
131. static openInvite = (token) => {
132. let rec = token == null || hlTypeName(token) != 'String' || token.length > 64 ? null : first(invitesTable.find('hash', sha256(token)))
133. 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.' } }
134. let s = stateOf(rec)
135. if (s != 'open') { return { status = 410 title = s == 'used' ? 'Invitation already used' : (s == 'expired' ? 'Invitation expired' : 'Invitation withdrawn') error = problemOf(s) } }
136. let rid = randomBytes(16)
137. requestsTable.put({ rid = rid app = rec.app returnUrl = rec.returnUrl invite = rec.id expires = now() + requestTtl })
138. return { rid = rid }
139. }
141. // THE CHOICE for an invite's request: the identity accepts it. Answers { error } or { url }
142. // (the app's return URL with ident_code and invite). An identity that already accepted this
143. // invite may pass again without taking another use.
144. static grantInvite = (accountId, rid, identityId) => {
145. let rq = requestOf(rid)
146. if (rq == null) { return { error = 'this login request is unknown or expired — open the invitation link again' } }
147. let rec = isId(rq.invite) ? invitesTable.fetch(rq.invite) : null
148. if (rec == null || rec.app != rq.app.id) { return { error = 'this invitation no longer exists' } }
149. if (ownIdentity(accountId, identityId) == null) { return { error = 'no such identity' } }
150. let conn = connectionOf(rq.app.id, identityId)
151. let list = acceptedList(rec)
152. let s = stateOf(rec)
153. if (s == 'revoked') { return { error = problemOf(s) } }
154. let mine = identitiesTable.fetch(identityId).shortId
155. if (!list.includes(mine) && !(conn.appIdentity != null && list.includes(conn.appIdentity))) {
156. if (s != 'open') { return { error = problemOf(s) } }
157. list.push(mine)
158. invitesTable.update(rec.id, merged(rec, { acceptedBy = list.join(' ') }))
159. }
160. let code = issueCode(rq.app.id, identityId)
161. let r = first(requestsTable.find('rid', rid))
162. if (r != null) { requestsTable.delete(r.id) }
163. let sep = rq.returnUrl.includes('?') ? '&' : '?'
164. return { url = rq.returnUrl + sep + 'ident_code=' + code + '&invite=' + rec.id }
165. }