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
tests/unit/api-authz.test.tsmodified+54-2
Changes to tests/unit/api-authz.test.ts
@@ -22,11 +22,23 @@ function routeBlock(path: string): string {
2222 return end === -1 ? rest : rest.slice(0, end)
2323}
2424
25const READ_ENDPOINTS = [
25/**
26 * The four reads a machine key may reach (#67), and nothing else.
27 *
28 * These are gated by `requireSiteRead`, which takes a read key issued for the
29 * site OR falls back to the same viewer check as everything below. They drop
30 * `.middleware('auth')` because it 401s before the handler and would refuse a
31 * key before it could be read — the real check is in the gate, which is
32 * asserted separately.
33 */
34const KEY_READABLE = [
2635 '/api/sites/{siteId}/stats',
2736 '/api/sites/{siteId}/timeseries',
2837 '/api/sites/{siteId}/pages',
2938 '/api/sites/{siteId}/referrers',
39]
40
41const READ_ENDPOINTS = [
3042 '/api/sites/{siteId}/events',
3143 '/api/sites/{siteId}/entry-pages',
3244 '/api/sites/{siteId}/exit-pages',
@@ -45,6 +57,42 @@ const TOP_DIMENSIONS = [
4557 '/api/sites/{siteId}/utm/campaigns',
4658]
4759
60describe('guardrail: a read key reaches exactly the reads it was issued for', () => {
61 // The point of a site key is that it is narrower than a person. If it could
62 // reach every /api/sites/{siteId}/* route, it would be a worse version of the
63 // user token it replaces, so the set it reaches is pinned here rather than
64 // left to whoever edits a route next.
65 for (const path of KEY_READABLE) {
66 test(`GET ${path} is gated by requireSiteRead`, () => {
67 const block = routeBlock(path)
68 expect(block).not.toBe('')
69 expect(block).toContain('requireSiteRead(request, siteId)')
70 })
71 }
72
73 test('no other route is gated by requireSiteRead', () => {
74 const gated = analytics.split('requireSiteRead(request, siteId)').length - 1
75 // One call per allowlisted route, plus the definition's own signature line
76 // does not match this call shape.
77 expect(gated).toBe(KEY_READABLE.length)
78 })
79
80 test('requireSiteRead still enforces viewer for a person', () => {
81 // Without this the four routes above would have no role check at all for a
82 // signed-in caller: dropping .middleware('auth') on them is only safe
83 // because the fallback is the same gate the rest of the file uses.
84 const i = analytics.indexOf('async function requireSiteRead(')
85 expect(i).toBeGreaterThan(-1)
86 const end = analytics.indexOf('\nasync function requireSiteRole(', i)
87 expect(end).toBeGreaterThan(i)
88 const body = analytics.slice(i, end)
89 expect(body).toContain('requireSiteRole(request, siteId, \'viewer\')')
90 // And it only accepts something shaped like a key — anything else falls
91 // through to the person check rather than being trusted.
92 expect(body).toContain('looksLikeReadKey(presented)')
93 })
94})
95
4896describe('guardrail: site-scoped read endpoints require at least viewer', () => {
4997 // These were owner-gated until #19, which is why an invited colleague could not
5098 // read a single report. The requirement is now a RANK, and the rank has to be
@@ -160,7 +208,11 @@ describe('guardrail: no site-scoped endpoint is left ungated', () => {
160208 const rest = analytics.slice(i)
161209 const end = rest.indexOf('\nroute.')
162210 const block = end === -1 ? rest : rest.slice(0, end)
163 expect(block).toMatch(/requireSiteRole\(request, siteId, '(viewer|admin|owner)'\)|requireSiteOwner\(request, siteId\)/)
211 // requireSiteRead counts: it takes a read key issued for this site, and
212 // otherwise defers to requireSiteRole(..., 'viewer') — asserted above, so
213 // accepting it here does not widen what "gated" means. The set of routes
214 // allowed to use it is pinned above too.
215 expect(block).toMatch(/requireSiteRole\(request, siteId, '(viewer|admin|owner)'\)|requireSiteOwner\(request, siteId\)|requireSiteRead\(request, siteId\)/)
164216 })
165217 }
166218})