also looking at this
A read-scoped site key, so a Stacks dashboard can read analytics without a person's credentials
#68
7 files
+550
-11
| @@ -20,6 +20,7 @@ import { formatCount, renderBadge, renderSparkline, sanitizeLabel } from '../app | ||
| 20 | 20 | import { ASSIGNABLE_ROLES, isAssignableRole, listReachableSites, listSiteMembers, resolveSiteRole, satisfies, siteExists, type SiteRole } from '../app/Analytics/access' |
| 21 | 21 | import { ALERT_CONDITIONS, ALERT_METRICS, isAlertCondition, isAlertMetric, isRelative } from '../app/Analytics/alerts' |
| 22 | 22 | import { planForSite } from '../app/Analytics/entitlements' |
| 23 | import { authorizeRead, looksLikeReadKey, newReadKey, shouldRecordUse } from '../app/Support/read-key' | |
| 23 | 24 | import { normalizeEnvironment } from '../app/Analytics/environment' |
| 24 | 25 | import { serializeEventProperties } from '../app/Analytics/event-properties' |
| 25 | 26 | import { expiryFrom, hashToken, inviteRefusal, looksLikeEmail, mintToken, normalizeEmail } from '../app/Analytics/invites' |
| @@ -809,6 +810,49 @@ function authUserId(request: HandlerRequest): string | null { | ||
| 809 | 810 | * conceal and collapsing the two would only make real 404s undebuggable. The |
| 810 | 811 | * secret is the data, and that is what the role check protects. |
| 811 | 812 | */ |
| 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 | */ | |
| 828 | async 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. */ | |
| 847 | async 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 | ||
| 812 | 856 | async function requireSiteRole(request: HandlerRequest, siteId: string, required: SiteRole): Promise<Response | null> { |
| 813 | 857 | const uid = authUserId(request) |
| 814 | 858 | if (!uid) |
| @@ -1011,6 +1055,40 @@ route.post('/api/sites/{siteId}/members', async (request) => { | ||
| 1011 | 1055 | return json({ members: await listSiteMembers(siteId) }) |
| 1012 | 1056 | }).middleware('auth').skipCsrf() |
| 1013 | 1057 | |
| 1058 | route.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. | |
| 1067 | route.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. | |
| 1082 | route.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 | ||
| 1014 | 1092 | route.options('/api/sites/{siteId}/members/{userId}', () => new Response(null, { status: 204, headers: CORS })) |
| 1015 | 1093 | |
| 1016 | 1094 | route.delete('/api/sites/{siteId}/members/{userId}', async (request) => { |
| @@ -3559,7 +3637,8 @@ route.delete('/api/sites/{siteId}/visitors/{visitorId}', async (request) => { | ||
| 3559 | 3637 | |
| 3560 | 3638 | route.get('/api/sites/{siteId}/stats', async (request) => { |
| 3561 | 3639 | 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) | |
| 3563 | 3642 | if (denied) |
| 3564 | 3643 | return denied |
| 3565 | 3644 | const { from, to } = window(request) |
| @@ -3583,11 +3662,12 @@ route.get('/api/sites/{siteId}/stats', async (request) => { | ||
| 3583 | 3662 | sessions: Number(row?.sessions ?? 0), |
| 3584 | 3663 | range: { from, to }, |
| 3585 | 3664 | }) |
| 3586 | }).middleware('auth') | |
| 3665 | }) | |
| 3587 | 3666 | |
| 3588 | 3667 | route.get('/api/sites/{siteId}/timeseries', async (request) => { |
| 3589 | 3668 | 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) | |
| 3591 | 3671 | if (denied) |
| 3592 | 3672 | return denied |
| 3593 | 3673 | const { from, to } = window(request) |
| @@ -3606,11 +3686,12 @@ route.get('/api/sites/{siteId}/timeseries', async (request) => { | ||
| 3606 | 3686 | if ('response' in result) |
| 3607 | 3687 | return result.response |
| 3608 | 3688 | return json({ series: result.rows }) |
| 3609 | }).middleware('auth') | |
| 3689 | }) | |
| 3610 | 3690 | |
| 3611 | 3691 | route.get('/api/sites/{siteId}/pages', async (request) => { |
| 3612 | 3692 | 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) | |
| 3614 | 3695 | if (denied) |
| 3615 | 3696 | return denied |
| 3616 | 3697 | const { from, to } = window(request) |
| @@ -3629,11 +3710,12 @@ route.get('/api/sites/{siteId}/pages', async (request) => { | ||
| 3629 | 3710 | if ('response' in result) |
| 3630 | 3711 | return result.response |
| 3631 | 3712 | return json({ pages: result.rows }) |
| 3632 | }).middleware('auth') | |
| 3713 | }) | |
| 3633 | 3714 | |
| 3634 | 3715 | route.get('/api/sites/{siteId}/referrers', async (request) => { |
| 3635 | 3716 | 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) | |
| 3637 | 3719 | if (denied) |
| 3638 | 3720 | return denied |
| 3639 | 3721 | const { from, to } = window(request) |
| @@ -3652,7 +3734,7 @@ route.get('/api/sites/{siteId}/referrers', async (request) => { | ||
| 3652 | 3734 | if ('response' in result) |
| 3653 | 3735 | return result.response |
| 3654 | 3736 | return json({ referrers: result.rows }) |
| 3655 | }).middleware('auth') | |
| 3737 | }) | |
| 3656 | 3738 | |
| 3657 | 3739 | // Owner-gated "top <dimension>" reports over page_views, so every dashboard |
| 3658 | 3740 | // breakdown has a documented JSON endpoint too (issue #15). `column` is always a |