ReviewOS

also looking at this

stacks/analyticshq

A read-scoped site key, so a Stacks dashboard can read analytics without a person's credentials

#68
Merged glennmichael123 wants to merge feat/read-scoped-site-key into main
7 files +550 -11
routes/analytics.tsmodified+90-8
Changes to routes/analytics.ts
@@ -20,6 +20,7 @@ import { formatCount, renderBadge, renderSparkline, sanitizeLabel } from '../app
2020import { ASSIGNABLE_ROLES, isAssignableRole, listReachableSites, listSiteMembers, resolveSiteRole, satisfies, siteExists, type SiteRole } from '../app/Analytics/access'
2121import { ALERT_CONDITIONS, ALERT_METRICS, isAlertCondition, isAlertMetric, isRelative } from '../app/Analytics/alerts'
2222import { planForSite } from '../app/Analytics/entitlements'
23import { authorizeRead, looksLikeReadKey, newReadKey, shouldRecordUse } from '../app/Support/read-key'
2324import { normalizeEnvironment } from '../app/Analytics/environment'
2425import { serializeEventProperties } from '../app/Analytics/event-properties'
2526import { expiryFrom, hashToken, inviteRefusal, looksLikeEmail, mintToken, normalizeEmail } from '../app/Analytics/invites'
@@ -809,6 +810,49 @@ function authUserId(request: HandlerRequest): string | null {
809810 * conceal and collapsing the two would only make real 404s undebuggable. The
810811 * secret is the data, and that is what the role check protects.
811812 */
813/**
814 * Gate a site-scoped read on a viewer role, or on a read key issued for the
815 * site (#67).
816 *
817 * Only the reads named on that issue call this — the stats summary, the time
818 * series, and the top pages and referrers. Every other `/api/sites/{siteId}/*`
819 * route keeps asking for a person, so a machine key reaches exactly the four
820 * endpoints it was issued for rather than all forty-odd by default. Adding one
821 * is calling this instead of requireSiteRole, deliberately one line per route.
822 *
823 * These four drop `.middleware('auth')`, which 401s before the handler and so
824 * would refuse a key before it could be read. Nothing is lost: that middleware
825 * was defence in depth behind requireSiteRole, which does the real check and
826 * still answers 401 when no credential resolves.
827 */
828async function requireSiteRead(request: HandlerRequest, siteId: string): Promise<Response | null> {
829 // Read off the header rather than a bearerToken() helper: HandlerRequest
830 // declares no such method here, and line 3272 reads the same header the same
831 // way, so this stays consistent with the rest of the file.
832 const presented = String(request.headers?.get?.('authorization') ?? '').replace(/^Bearer\s+/i, '')
833 if (!looksLikeReadKey(presented))
834 return requireSiteRole(request, siteId, 'viewer')
835
836 const row = (await pgq('SELECT id, read_key, read_key_last_used_at FROM sites WHERE id = ? LIMIT 1', [String(siteId)]))?.[0]
837 const site = row ? { id: String(row.id), read_key: row.read_key == null ? null : String(row.read_key), read_key_last_used_at: row.read_key_last_used_at == null ? null : String(row.read_key_last_used_at) } : null
838 const verdict = authorizeRead(site, presented)
839 if (!verdict.ok)
840 return json({ error: verdict.error }, verdict.status)
841 if (site)
842 await recordReadKeyUse(site)
843 return null
844}
845
846/** Stamp the key as used, at most once a minute — see LAST_USED_RESOLUTION_MS. */
847async function recordReadKeyUse(site: { id: string, read_key_last_used_at?: string | null }): Promise<void> {
848 const now = new Date()
849 if (!shouldRecordUse(site.read_key_last_used_at, now))
850 return
851 // Never let the stamp fail a read: it aids revoking a key, it does not
852 // authorise one.
853 await pgq('UPDATE sites SET read_key_last_used_at = ? WHERE id = ?', [now.toISOString(), String(site.id)]).catch(() => {})
854}
855
812856async function requireSiteRole(request: HandlerRequest, siteId: string, required: SiteRole): Promise<Response | null> {
813857 const uid = authUserId(request)
814858 if (!uid)
@@ -1011,6 +1055,40 @@ route.post('/api/sites/{siteId}/members', async (request) => {
10111055 return json({ members: await listSiteMembers(siteId) })
10121056}).middleware('auth').skipCsrf()
10131057
1058route.options('/api/sites/{siteId}/read-key', () => new Response(null, { status: 204, headers: CORS }))
1059
1060// Issue (or replace) a site's read key. Admin-only.
1061//
1062// The credential a server presents to read this site's analytics without a
1063// person's account behind it (#67). Returned here and nowhere else: it is a
1064// secret, so it is shown once and afterwards the site only reports that a key
1065// exists and when it was last used. Losing it means issuing another, and the
1066// previous key stops working the moment that lands.
1067route.post('/api/sites/{siteId}/read-key', async (request) => {
1068 const siteId = request.params.siteId
1069 const denied = await requireSiteRole(request, siteId, 'admin')
1070 if (denied)
1071 return denied
1072
1073 const key = newReadKey()
1074 // A new key starts with no last-used stamp: keeping the old one would read
1075 // as "used before it existed".
1076 await pgq('UPDATE sites SET read_key = ?, read_key_last_used_at = NULL WHERE id = ?', [key, siteId])
1077 return json({ read_key: key })
1078}).middleware('auth').skipCsrf()
1079
1080// Revoke a site's read key. Admin-only. Anything still presenting it is
1081// refused on its next request.
1082route.delete('/api/sites/{siteId}/read-key', async (request) => {
1083 const siteId = request.params.siteId
1084 const denied = await requireSiteRole(request, siteId, 'admin')
1085 if (denied)
1086 return denied
1087
1088 await pgq('UPDATE sites SET read_key = NULL, read_key_last_used_at = NULL WHERE id = ?', [siteId])
1089 return json({ revoked: true })
1090}).middleware('auth').skipCsrf()
1091
10141092route.options('/api/sites/{siteId}/members/{userId}', () => new Response(null, { status: 204, headers: CORS }))
10151093
10161094route.delete('/api/sites/{siteId}/members/{userId}', async (request) => {
@@ -3559,7 +3637,8 @@ route.delete('/api/sites/{siteId}/visitors/{visitorId}', async (request) => {
35593637
35603638route.get('/api/sites/{siteId}/stats', async (request) => {
35613639 const siteId = request.params.siteId
3562 const denied = await requireSiteRole(request, siteId, 'viewer')
3640 // A viewer on this site, or a read key issued for it (#67).
3641 const denied = await requireSiteRead(request, siteId)
35633642 if (denied)
35643643 return denied
35653644 const { from, to } = window(request)
@@ -3583,11 +3662,12 @@ route.get('/api/sites/{siteId}/stats', async (request) => {
35833662 sessions: Number(row?.sessions ?? 0),
35843663 range: { from, to },
35853664 })
3586}).middleware('auth')
3665})
35873666
35883667route.get('/api/sites/{siteId}/timeseries', async (request) => {
35893668 const siteId = request.params.siteId
3590 const denied = await requireSiteRole(request, siteId, 'viewer')
3669 // A viewer on this site, or a read key issued for it (#67).
3670 const denied = await requireSiteRead(request, siteId)
35913671 if (denied)
35923672 return denied
35933673 const { from, to } = window(request)
@@ -3606,11 +3686,12 @@ route.get('/api/sites/{siteId}/timeseries', async (request) => {
36063686 if ('response' in result)
36073687 return result.response
36083688 return json({ series: result.rows })
3609}).middleware('auth')
3689})
36103690
36113691route.get('/api/sites/{siteId}/pages', async (request) => {
36123692 const siteId = request.params.siteId
3613 const denied = await requireSiteRole(request, siteId, 'viewer')
3693 // A viewer on this site, or a read key issued for it (#67).
3694 const denied = await requireSiteRead(request, siteId)
36143695 if (denied)
36153696 return denied
36163697 const { from, to } = window(request)
@@ -3629,11 +3710,12 @@ route.get('/api/sites/{siteId}/pages', async (request) => {
36293710 if ('response' in result)
36303711 return result.response
36313712 return json({ pages: result.rows })
3632}).middleware('auth')
3713})
36333714
36343715route.get('/api/sites/{siteId}/referrers', async (request) => {
36353716 const siteId = request.params.siteId
3636 const denied = await requireSiteRole(request, siteId, 'viewer')
3717 // A viewer on this site, or a read key issued for it (#67).
3718 const denied = await requireSiteRead(request, siteId)
36373719 if (denied)
36383720 return denied
36393721 const { from, to } = window(request)
@@ -3652,7 +3734,7 @@ route.get('/api/sites/{siteId}/referrers', async (request) => {
36523734 if ('response' in result)
36533735 return result.response
36543736 return json({ referrers: result.rows })
3655}).middleware('auth')
3737})
36563738
36573739// Owner-gated "top <dimension>" reports over page_views, so every dashboard
36583740// breakdown has a documented JSON endpoint too (issue #15). `column` is always a