@bakery-framework/plugin-analytics 1.2.3 → 2.0.0-alpha.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bakery-framework/plugin-analytics",
-  "version": "1.2.3",
+  "version": "2.0.0-alpha.1",
   "description": "Bakery analytics plugin.",
   "keywords": [
     "bakery",
@@ -34,7 +34,7 @@
     "!src/tests"
   ],
   "dependencies": {
-    "@bakery-framework/core": "^1.0.0"
+    "@bakery-framework/core": "^1.2.3"
   },
   "engines": {
     "bun": ">=1.3.14"

package/src/endpoints/stats.ts

@@ -1,7 +1,10 @@
 import { Bakery } from '@bakery-framework/core/core/bakery'
-import { DASHPASS_SESSION_KEY, Session } from '@bakery-framework/core/session'
+import { Session } from '@bakery-framework/core/session'
 import type { JsonResponseData } from '@bakery-framework/core/utils/common'
-import { response } from '@bakery-framework/core/utils/http'
+import {
+  requestHasCredential,
+  response,
+} from '@bakery-framework/core/utils/http'
 import * as core from '../core'
 import { saveAnalyticsData } from '../storage-sqlite'
 import { timescaleToMs } from '../timescale'
@@ -77,14 +80,45 @@ export function computeStats(
 export type AnalyticsStats = ReturnType<typeof computeStats>
 
 /**
- * True when the caller may read analytics. Fails **closed** when DASHPASS is
- * unset, matching the dashboard's behaviour — this previously returned
- * "authorized" in that case, so the documented "disabled" posture actually
- * exposed process stats and top pages to anyone.
+ * A request predicate, for apps that gate by their own roles rather than (or
+ * as well as) a shared key. Returning `true` admits; throwing or returning
+ * anything else denies (convention 2).
  */
-export function isAnalyticsAuthorized(req: Request): boolean {
-  if (!process.env.DASHPASS) return false
-  return Boolean(req.session?.get(DASHPASS_SESSION_KEY))
+export type AuthorizeFn = (req: Request) => boolean | Promise<boolean>
+
+/**
+ * Analytics owns the auth for its endpoints, and the dashboard delegates to
+ * it (`isAnalyticsAuthorized`) — the analytics key *is* the dashboard key.
+ * Two doors, both fail closed and both off until configured:
+ *
+ *   - the shared `credential` (`x-analytics-key`, Bearer, or `?analytics-key=`)
+ *   - an optional `authorize(req)` predicate for role-based access
+ *
+ * Neither configured means analytics is closed to everyone, which is the safe
+ * default. Note `isAnalyticsAuthorized` is sync-fast on the credential path
+ * and only awaits when a predicate is present — the websocket `canHandle`
+ * needs a boolean, so a predicate makes the check async there too.
+ */
+let credential: string | undefined
+let authorizeFn: AuthorizeFn | undefined
+
+export function setAnalyticsCredential(value: string | undefined): void {
+  credential = value
+}
+
+export function setAnalyticsAuthorize(fn: AuthorizeFn | undefined): void {
+  authorizeFn = fn
+}
+
+export async function isAnalyticsAuthorized(req: Request): Promise<boolean> {
+  if (requestHasCredential(req, credential, 'analytics-key')) return true
+  if (!authorizeFn) return false
+  try {
+    return (await authorizeFn(req)) === true
+  } catch {
+    // A predicate that throws is indeterminate, and indeterminate is denied.
+    return false
+  }
 }
 
 /**
@@ -95,9 +129,13 @@ export function isAnalyticsAuthorized(req: Request): boolean {
  * the envelope carries no `data`, which is what makes it assignable into every
  * caller's own payload type.
  */
-function checkDashpassAuth(req: Request): JsonResponseData<undefined> | null {
-  if (isAnalyticsAuthorized(req)) return null
-  return process.env.DASHPASS
+async function checkAnalyticsAuth(
+  req: Request,
+): Promise<JsonResponseData<undefined> | null> {
+  if (await isAnalyticsAuthorized(req)) return null
+  // Armed-but-unauthorised is a 401; nothing configured is a 404 that does
+  // not advertise the endpoint at all.
+  return credential || authorizeFn
     ? response.json.error<undefined>(401, 'Unauthorized')
     : response.json.error<undefined>(404, 'Not Found')
 }
@@ -105,7 +143,7 @@ function checkDashpassAuth(req: Request): JsonResponseData<undefined> | null {
 export async function handleResetRequest(
   req: Request,
 ): Promise<JsonResponseData<undefined>> {
-  const authError = checkDashpassAuth(req)
+  const authError = await checkAnalyticsAuth(req)
   if (authError) return authError
 
   core.history1m.length = 0
@@ -124,7 +162,7 @@ export async function handleStatsRequest(
   req: Request,
   url: URL,
 ): Promise<JsonResponseData<AnalyticsStats | undefined>> {
-  const authError = checkDashpassAuth(req)
+  const authError = await checkAnalyticsAuth(req)
   if (authError) return authError
 
   const timescale = url.searchParams.get('timescale') || '1m'

package/src/endpoints/websocket.ts

@@ -8,8 +8,11 @@ export class AnalyticsWSHandler extends WebSocketHandler {
   // The upgrade is dispatched before any plugin hook runs, so the auth check
   // has to live here. Without it this socket served the same payload the HTTP
   // stats endpoint guards — and pushed it live every second.
-  static canHandle(path: string, req?: Request): boolean {
+  static async canHandle(path: string, req?: Request): Promise<boolean> {
     if (path !== '/_analytics_ws') return false
+    // Async because the auth may run an `authorize` predicate; the registry
+    // awaits a promise-returning `canHandle`. A browser cannot set a header on
+    // a WebSocket, so the credential arrives as `?analytics-key=`.
     return req ? isAnalyticsAuthorized(req) : false
   }
 

package/src/index.ts

@@ -15,12 +15,41 @@ export {
   recordRouteHit,
 } from './core'
 
-export default function analyticsPlugin() {
+export type { AuthorizeFn } from './endpoints/stats'
+
+export interface AnalyticsPluginOptions {
+  /**
+   * A shared access key for the analytics endpoints and websocket, typically
+   * from the environment:
+   *
+   * ```ts
+   * analyticsPlugin({ credential: import.meta.env.ANALYTICS_KEY })
+   * ```
+   *
+   * Presented as `Authorization: Bearer`, an `x-analytics-key` header, or an
+   * `?analytics-key=` query. Checked in constant time; unset or empty means
+   * this door is closed. The same key gates the dashboard, which delegates
+   * its auth here.
+   */
+  credential?: string
+
+  /**
+   * A request predicate for role-based access, as an alternative or addition
+   * to the shared key: `authorize: req => req.session.get('role') === 'admin'`.
+   * Either door admits; both fail closed. With neither, analytics is off.
+   */
+  authorize?: import('./endpoints/stats').AuthorizeFn
+}
+
+export default function analyticsPlugin(options: AnalyticsPluginOptions = {}) {
   return definePlugin({
     name: 'analytics',
     async setup() {
       const { setupAnalytics } = await import('./setup')
-      setupAnalytics()
+      setupAnalytics({
+        credential: options.credential,
+        authorize: options.authorize,
+      })
     },
     onRoute(req) {
       const url: URL = (req as any).__parsedUrl || new URL(req.url)

package/src/setup.ts

@@ -10,7 +10,13 @@ import { response } from '@bakery-framework/core/utils/http'
 import * as core from './core'
 import { BOOT_MAX_ITEMS } from './core'
 import type { AnalyticsStats } from './endpoints/stats'
-import { handleResetRequest, handleStatsRequest } from './endpoints/stats'
+import {
+  type AuthorizeFn,
+  handleResetRequest,
+  handleStatsRequest,
+  setAnalyticsAuthorize,
+  setAnalyticsCredential,
+} from './endpoints/stats'
 import { AnalyticsWSHandler } from './endpoints/websocket'
 import * as storageSqlite from './storage-sqlite'
 
@@ -179,7 +185,24 @@ export function handleAnalyticsRequest(
   return analyticsRoutes(req)
 }
 
-export function setupAnalytics() {
+let registered = false
+
+export function setupAnalytics(
+  options: { credential?: string; authorize?: AuthorizeFn } = {},
+) {
+  // Auth is (re)applied every call — last config wins — so the dashboard
+  // bringing analytics up with the shared key overrides a bare
+  // `analyticsPlugin()`, whichever order they registered in.
+  setAnalyticsCredential(options.credential)
+  setAnalyticsAuthorize(options.authorize)
+
+  // The rest runs once. Analytics is now a hard dependency of the dashboard,
+  // so both may set it up in one process; the handler registrations are
+  // idempotent but the shutdown hook and data load are not, and a doubled
+  // load would race two reads of the same file.
+  if (registered) return
+  registered = true
+
   Bakery.handlers.fetch.set(AnalyticsHandler, 110)
   Bakery.handlers.websocket.set(AnalyticsWSHandler)
   void loadAnalyticsData()