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/read-key.test.tsadded+115-0
Changes to tests/unit/read-key.test.ts
@@ -0,0 +1,115 @@
1import { describe, expect, test } from 'bun:test'
2import { authorizeRead, LAST_USED_RESOLUTION_MS, looksLikeReadKey, newReadKey, sameKey, shouldRecordUse } from '../../app/Support/read-key'
3
4const KEY = newReadKey()
5const site = { id: 'demo', read_key: KEY }
6
7describe('newReadKey', () => {
8 test('is prefixed and carries 256 bits of hex', () => {
9 expect(KEY.startsWith('ahq_read_')).toBe(true)
10 expect(KEY.slice('ahq_read_'.length)).toMatch(/^[0-9a-f]{64}$/)
11 })
12
13 test('does not repeat', () => {
14 const keys = new Set(Array.from({ length: 200 }, () => newReadKey()))
15 expect(keys.size).toBe(200)
16 })
17})
18
19describe('looksLikeReadKey', () => {
20 test('accepts a key it minted', () => {
21 expect(looksLikeReadKey(KEY)).toBe(true)
22 })
23
24 test('rejects anything else a bearer header might carry', () => {
25 // The prefix is what keeps a read key out of Auth.getUserFromToken, so a
26 // user's token and an ingest key must never pass for one.
27 for (const value of [
28 '',
29 null,
30 undefined,
31 'some_other_credential_shape_entirely',
32 'eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxIn0.sig',
33 `${'ahq_read_'}${'z'.repeat(64)}`,
34 `${'ahq_read_'}${'a'.repeat(63)}`,
35 `${'ahq_read_'}${'a'.repeat(65)}`,
36 KEY.toUpperCase(),
37 ])
38 expect(looksLikeReadKey(value)).toBe(false)
39 })
40})
41
42describe('sameKey', () => {
43 test('matches an identical key and nothing else', () => {
44 expect(sameKey(KEY, KEY)).toBe(true)
45 expect(sameKey(KEY, newReadKey())).toBe(false)
46 })
47
48 test('is false on a shared prefix, not just a differing first byte', () => {
49 const other = `${KEY.slice(0, -1)}${KEY.endsWith('a') ? 'b' : 'a'}`
50 expect(sameKey(other, KEY)).toBe(false)
51 })
52
53 test('does not throw on a length mismatch', () => {
54 expect(sameKey('short', KEY)).toBe(false)
55 expect(sameKey(KEY, 'short')).toBe(false)
56 })
57})
58
59describe('authorizeRead', () => {
60 test('allows the site its own key', () => {
61 expect(authorizeRead(site, KEY)).toEqual({ ok: true })
62 })
63
64 test('refuses an unknown site with 404', () => {
65 expect(authorizeRead(null, KEY)).toEqual({ ok: false, status: 404, error: 'Site not found' })
66 expect(authorizeRead(undefined, KEY)).toEqual({ ok: false, status: 404, error: 'Site not found' })
67 })
68
69 test('refuses a site with no key issued, whatever is presented', () => {
70 // Guards `null === null`: no key configured must never authorise, not even
71 // against a caller presenting nothing.
72 for (const presented of [KEY, null, undefined, ''])
73 expect(authorizeRead({ ...site, read_key: null }, presented).ok).toBe(false)
74 // Narrowed rather than reached into: the refusal shape only carries a
75 // status on the failing branch of the union.
76 const refused = authorizeRead({ ...site, read_key: null }, KEY)
77 expect(refused.ok).toBe(false)
78 if (!refused.ok)
79 expect(refused.status).toBe(403)
80 })
81
82 test('refuses another project\'s key with 401', () => {
83 expect(authorizeRead(site, newReadKey())).toEqual({ ok: false, status: 401, error: 'Unauthorized' })
84 })
85
86 test('refuses a stored value that is not a well-formed key', () => {
87 // A column hand-edited to something short must not become a weak key.
88 expect(authorizeRead({ ...site, read_key: 'x' }, 'x').ok).toBe(false)
89 })
90})
91
92describe('shouldRecordUse', () => {
93 const now = new Date('2026-10-19T12:00:00.000Z')
94
95 test('records the first use', () => {
96 expect(shouldRecordUse(null, now)).toBe(true)
97 expect(shouldRecordUse(undefined, now)).toBe(true)
98 })
99
100 test('records again once the resolution has passed, and not before', () => {
101 const justBefore = new Date(now.getTime() - LAST_USED_RESOLUTION_MS + 1).toISOString()
102 const atResolution = new Date(now.getTime() - LAST_USED_RESOLUTION_MS).toISOString()
103 expect(shouldRecordUse(justBefore, now)).toBe(false)
104 expect(shouldRecordUse(atResolution, now)).toBe(true)
105 })
106
107 test('records when the stored stamp cannot be read', () => {
108 // Better an extra write than a key that never looks used.
109 expect(shouldRecordUse('not a date', now)).toBe(true)
110 })
111
112 test('accepts a Date as well as a string', () => {
113 expect(shouldRecordUse(new Date(now.getTime() - 1000), now)).toBe(false)
114 })
115})