ident

12.7 KB

1. // lib/api.hl — THE FUNCTION ROUTES (project.hl `routes`): the login button's GET /login, the app's server calls
2. // (exchange, migrate-ids, kinds, notify, invites), the selector's two CORS calls, the code request, the invite
3. // link, the code page, the offline probe. THIN WRAPPERS: check the method, the body (lib/api-helpers.hl strictBody)
4. // and the app's key + secret, call the topic function, answer. Shapes: README "How apps use ident",
5. // "How apps send notifications", "Invites". Statics only.
6. import { Response } from 'hl:http1'
7. import { reply, fail, redirect, strictBody, errorPage, field, inviteCaller, baseOf, hexId, refuse, corsHeaders, answer, caller } from './api-helpers.hl'
8. import { openRequest, exchange, migrateIds, appOfSecret, openInvite } from './apps.hl'
9. import { selectorList, codeOfPick } from './selector.hl'
10. import { createInvite, listInvites, revokeInvite, ownInvite, inviteRow } from './invites.hl'
11. import { registerKinds, sendNotification } from './notify.hl'
12. import { startLogin, pendingOf } from './login.hl'
13. import { accountOfSession } from './accounts.hl'
14. import { sendCode, sendInvite } from './mail.hl'
16. // ---- THE LOGIN BUTTON: GET /login?key=<api key>&return=<url> ---------------------------
17. // An unknown key or a return URL outside the app's origins → an error page, NEVER a
18. // redirect. Otherwise the request is parked under a random id (a page component cannot
19. // read the query, hybriel #18) and the browser goes to /signin/<rid>.
20. static appLogin = (route, req) => {
21. if (req.method != 'GET') { return errorPage(405, 'Method not allowed', 'Use a GET request.') }
22. let q = req.query != null ? req.query : {}
23. let r = openRequest(q.key, q['return'])
24. if (r.error != null) { return errorPage(400, 'Bad login request', r.error) }
25. return redirect('/signin/' + r.rid)
26. }
28. // ---- POST /api/migrate-ids { key, secret, finish? } → { ids: { <old per-app id>: <short id> } } (ident#23)
29. // the APP'S SERVER moves its stored users to the identities' short ids in one step; with
30. // `finish: true` the old per-app ids are dropped afterwards (they are gone for good).
31. static apiMigrateIds = (route, req) => {
32. if (req.method != 'POST') { return fail(405, 'POST only') }
33. let b = strictBody(req, { key = { type = 'String' required = true } secret = { type = 'String' required = true } finish = { type = 'Boolean' required = false } })
34. if (b.error != null) { return fail(400, b.error) }
35. let a = appOfSecret(b.body.key.trim(), b.body.secret.trim())
36. if (a == null) { return fail(401, 'unknown API key or wrong secret') }
37. return reply(200, migrateIds(a, b.body.finish == true))
38. }
40. // ---- POST /api/exchange { key, secret, code } → { identity } ---------------------------
41. // the APP'S SERVER trades the ident_code from its return URL for the app-specific
42. // identity's short id. Nothing else is handed out (CONCEPT.md "More fields").
43. static apiExchange = (route, req) => {
44. if (req.method != 'POST') { return fail(405, 'POST only') }
45. let b = strictBody(req, { key = { type = 'String' required = true } secret = { type = 'String' required = true } code = { type = 'String' required = true } })
46. if (b.error != null) { return fail(400, b.error) }
47. for (k of ['key' 'secret' 'code']) {
48. if (b.body[k].trim() == '') { return fail(400, 'missing field: ' + k) }
49. }
50. let r = exchange(b.body.key.trim(), b.body.secret.trim(), b.body.code.trim())
51. if (r.error != null) { return fail(r.status, r.error) }
52. return reply(200, { identity = r.identity })
53. }
55. // ---- THE SELECTOR's two calls (lib/selector.hl): the ident user is the cookie's ---------
56. // (hl:web hands a function route the cookie's session as req.session, hybriel#11)
57. static apiSelectorIdentities = (route, req) => { return selectorIdentities(req, req.session) }
58. static apiSelectorChoose = (route, req) => { return selectorChoose(req, req.session) }
60. // GET /api/selector/identities?key=
61. static selectorIdentities = (req, &session) => {
62. let c = caller(req)
63. if (c.error != null) { return refuse(c.status, c.error) }
64. if (req.method != 'GET') { return answer(c.origin, 405, { error = 'GET only' }) }
65. let me = accountOfSession(session)
66. if (me == null) { return answer(c.origin, 200, { signedIn = false identities = [] }) }
67. return answer(c.origin, 200, { signedIn = true identities = selectorList(c.app, me.id) })
68. }
70. // POST /api/selector/choose?key= { identity } (+ its OPTIONS preflight)
71. static selectorChoose = (req, &session) => {
72. let c = caller(req)
73. if (c.error != null) { return refuse(c.status, c.error) }
74. if (req.method == 'OPTIONS') {
75. let h = corsHeaders(c.origin)
76. h['Access-Control-Allow-Methods'] = 'POST'
77. h['Access-Control-Allow-Headers'] = 'Content-Type'
78. h['Access-Control-Max-Age'] = '600'
79. return new Response('', { status = 204 headers = h })
80. }
81. if (req.method != 'POST') { return answer(c.origin, 405, { error = 'POST only' }) }
82. let b = strictBody(req, { identity = { type = 'String' required = true } })
83. if (b.error != null) { return answer(c.origin, 400, { error = b.error }) }
84. let me = accountOfSession(session)
85. if (me == null) { return answer(c.origin, 401, { error = 'you are not signed in to ident' }) }
86. let code = codeOfPick(c.app, me.id, b.body.identity)
87. if (code != null) { return answer(c.origin, 200, { code = code }) }
88. return answer(c.origin, 400, { error = 'no such identity' })
89. }
91. // ---- POST /api/code { email } → { email }: THE ONE WAY TO GET A LOGIN CODE MAILED --------
92. // (the sign-in form of `/` and `/signin/<rid>` fetches it). Limits: per address (3 / 10 min)
93. // and per client IP (lib/login-helpers.hl ipBucket: 10 / 10 min, 30 / 24 h) → 429 with the reason.
94. // THE CLIENT IP is the X-Client-IP header and nothing else: nginx on Byrodin sets it and
95. // overwrites any the client sent (/CONTAINERS/web/nginx/conf.d/cloudflare-client-ip.conf).
96. // CF-Connecting-IP / X-Forwarded-For / X-Real-IP are NEVER read (a client could forge them).
97. // Without the header (dev, no nginx) every request shares ONE bucket ('direct'):
98. // (hl:web's req.remoteAddress, hybriel#25, would be nginx's address behind the proxy.)
99. // A function route, not a face: a face gets no request (no headers), and the per-IP limit needs the IP.
100. static apiCode = (route, req) => {
101. if (req.method != 'POST') { return fail(405, 'POST only') }
102. let b = strictBody(req, { email = { type = 'String' required = true } })
103. if (b.error != null) { return fail(400, b.error) }
104. let r = startLogin(b.body.email, req.headers['x-client-ip'])
105. if (r.error != null) { return fail(r.limited == true ? 429 : 400, r.error) }
106. sendCode(r.email, r.code)
107. return reply(200, { email = r.email })
108. }
110. // ---- NOTIFICATIONS (piece 4, lib/notify.hl; README "How apps send notifications") -------
111. // The APP'S SERVER, with its key + secret. Strict JSON bodies; delivery is not built yet
112. // (pieces 5/6) — ident stores the notification and its channels, and the user reads it
113. // in the inbox (/inbox).
114. // POST /api/kinds { key, secret, kinds: [{ name, push, email }] } → { kinds }
115. // POST /api/notify { key, secret, identity, name, text, icon?, link?, urgent? } → { id }
116. static apiKinds = (route, req) => {
117. if (req.method != 'POST') { return fail(405, 'POST only') }
118. let b = strictBody(req, { key = { type = 'String' required = true } secret = { type = 'String' required = true } kinds = { type = 'List' required = true } })
119. if (b.error != null) { return fail(400, b.error) }
120. let a = appOfSecret(b.body.key, b.body.secret)
121. if (a == null) { return fail(401, 'unknown API key or wrong secret') }
122. let r = registerKinds(a, b.body.kinds)
123. if (r.error != null) { return fail(r.status, r.error) }
124. return reply(200, { kinds = r.kinds })
125. }
126. static apiNotify = (route, req) => {
127. if (req.method != 'POST') { return fail(405, 'POST only') }
128. let b = strictBody(req, { key = { type = 'String' required = true } secret = { type = 'String' required = true } identity = { type = 'String' required = true } name = { type = 'String' required = true } text = { type = 'String' required = true } icon = { type = 'String' required = false } link = { type = 'String' required = false } urgent = { type = 'Boolean' required = false } })
129. if (b.error != null) { return fail(400, b.error) }
130. let r = sendNotification(b.body)
131. if (r.error != null) { return fail(r.status, r.error) }
132. return reply(200, { id = r.id })
133. }
135. // ---- INVITES (ident#22, lib/invites.hl; README "Invites") ----------------------------------------
136. // The APP'S SERVER, key + secret, strict JSON bodies:
137. // POST /api/invites { key, secret, project, role, return, uses?, days?, email? } → { id, url, state, … }
138. // POST /api/invites/list { key, secret, project? } → { invites: [...] }
139. // POST /api/invites/get { key, secret, id } → { invite }
140. // POST /api/invites/revoke { key, secret, id } → { invite }
141. // and the PERSON: GET /invite/<token> → the login flow (or an error page: used, expired, withdrawn).
142. static apiInvites = (route, req) => {
143. let c = inviteCaller(req, { key = field(true, 'String') secret = field(true, 'String') project = field(true, 'String') role = field(true, 'String') 'return' = field(true, 'String') uses = field(false, 'Number') days = field(false, 'Number') email = field(false, 'String') })
144. if (c.res != null) { return c.res }
145. let r = createInvite(c.app, c.body, baseOf(req))
146. if (r.error != null) { return fail(r.status, r.error) }
147. let mailed = false
148. if (r.mail != null) {
149. sendInvite(r.mail.to, r.url, c.app.name, r.invite.project, r.invite.role, r.mail.days)
150. mailed = true
151. }
152. return reply(200, { id = r.invite.id url = r.url state = r.invite.state project = r.invite.project role = r.invite.role uses = r.invite.uses expires = r.invite.expires mailed = mailed })
153. }
154. static apiInvitesList = (route, req) => {
155. let c = inviteCaller(req, { key = field(true, 'String') secret = field(true, 'String') project = field(false, 'String') })
156. if (c.res != null) { return c.res }
157. return reply(200, { invites = listInvites(c.app, c.body.project) })
158. }
159. static apiInvitesGet = (route, req) => {
160. let c = inviteCaller(req, { key = field(true, 'String') secret = field(true, 'String') id = field(true, 'String') })
161. if (c.res != null) { return c.res }
162. let r = ownInvite(c.app, c.body.id)
163. if (r == null) { return fail(404, 'no such invite') }
164. return reply(200, { invite = inviteRow(r) })
165. }
166. static apiInvitesRevoke = (route, req) => {
167. let c = inviteCaller(req, { key = field(true, 'String') secret = field(true, 'String') id = field(true, 'String') })
168. if (c.res != null) { return c.res }
169. let r = revokeInvite(c.app, c.body.id)
170. if (r.error != null) { return fail(r.status, r.error) }
171. return reply(200, { invite = r.invite })
172. }
173. static inviteLink = (route, req) => {
174. if (req.method != 'GET') { return errorPage(405, 'Method not allowed', 'Use a GET request.') }
175. let r = openInvite(route.params.token)
176. if (r.error != null) { return errorPage(r.status, r.title, r.error) }
177. return redirect('/signin/' + r.rid)
178. }
180. // ---- THE CODE PAGE: GET /code and /signin/<rid>/code (ident#20, mission 008 (old 032)) ------------
181. // Creator: "just make a /code where it checks a pending code". The page asks the SESSION
182. // (lib/login.hl pendingOf) whether a code it asked for is still waiting — unused, unexpired,
183. // not killed by wrong tries. Yes → Home renders its code step with that address (a reload
184. // shows it again). No, or already signed in → 302 back to the email form (`/` or
185. // `/signin/<rid>`), so a stale /code is never a dead end.
186. // A FUNCTION route because a component route cannot answer a redirect: it takes the
187. // cookie's session (req.session, hybriel#11) and renders `pageComponent` (Home) through the framework's own page
188. // render (`srv.page`, the same call a component route makes) with `step = 'code'`; project.hl hands in
189. // its server (by reference) and Home.
190. // Its signature since hybriel #105 (mission 048): page(match, session, host, headers) — the
191. // old page(match, req, session) still compiles but renders with req as the session (empty page).
192. static codePage = (route, req, &srv, pageComponent) => {
193. let rid = route.params.rid
194. // a rid is 32 hex (lib/apps.hl); anything else goes to `/` (it lands in a Location header)
195. if (rid != null && !hexId(rid)) { return redirect('/') }
196. let home = rid != null ? '/signin/' + rid : '/'
197. if (req.method != 'GET') { return redirect(home) }
198. let s = req.session
199. if (s == null || accountOfSession(s) != null || pendingOf(s) == null) { return redirect(home) }
200. let m = { route = { pattern = route.route.pattern component = pageComponent } kind = 'component' params = { rid = rid step = 'code' pending = pendingOf(s) } path = route.path }
201. return srv.page(m, s, srv.hostOf(req.headers['host']), srv.requestHeaders(req.headers))
202. }
204. static notFoundApi = (route, req) => { return fail(404, 'no such endpoint') }
206. // GET /api/online → 204: the shell's network probe (components/main.hl). Never cached, carries nothing.
207. static apiOnline = (route, req) => { return new Response('', { status = 204 headers = { 'Cache-Control' = 'no-store' } }) }