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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bakery-framework/plugin-analytics",
-  "version": "1.2.3",
+  "version": "2.0.0-alpha.11",
   "description": "Bakery analytics plugin.",
   "keywords": [
     "bakery",
@@ -25,6 +25,7 @@
   "main": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
+    "./setup": "./src/setup.ts",
     "./stats": "./src/endpoints/stats.ts",
     "./package.json": "./package.json"
   },
@@ -34,9 +35,9 @@
     "!src/tests"
   ],
   "dependencies": {
-    "@bakery-framework/core": "^1.0.0"
+    "@bakery-framework/core": "^2.0.0-alpha.11"
   },
   "engines": {
-    "bun": ">=1.3.14"
+    "bun": ">=1.4.0"
   }
 }

package/src/endpoints/stats.ts

@@ -1,7 +1,11 @@
 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 {
+  type AuthorizeFn,
+  requestHasCredential,
+  response,
+} from '@bakery-framework/core/utils/http'
 import * as core from '../core'
 import { saveAnalyticsData } from '../storage-sqlite'
 import { timescaleToMs } from '../timescale'
@@ -77,14 +81,49 @@ 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).
+ *
+ * Re-exported from core rather than declared here: the dashboard and
+ * db-explorer plugins need the same type, and three byte-identical copies of a
+ * security type drift the way the guards themselves already had.
  */
-export function isAnalyticsAuthorized(req: Request): boolean {
-  if (!process.env.DASHPASS) return false
-  return Boolean(req.session?.get(DASHPASS_SESSION_KEY))
+export type { AuthorizeFn } from '@bakery-framework/core/utils/http'
+
+/**
+ * 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 +134,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 +148,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 +167,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

@@ -1,4 +1,5 @@
 import { definePlugin } from '@bakery-framework/core/plugins'
+import { parsedUrl } from '@bakery-framework/core/utils/http'
 import { recordErrorPageHit, recordRouteHit } from './core'
 
 export {
@@ -15,15 +16,44 @@ 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)
+      const url = parsedUrl(req)
       recordRouteHit(req.method, url.pathname, url.search)
     },
     onStart: async server => {

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,53 @@ export function handleAnalyticsRequest(
   return analyticsRoutes(req)
 }
 
-export function setupAnalytics() {
+let registered = false
+
+export interface AnalyticsAuthOptions {
+  credential?: string
+  authorize?: AuthorizeFn
+}
+
+/**
+ * The auth half of `setupAnalytics`, split out from the once-only half.
+ *
+ * Auth is (re)applied on every call — last config wins — so the dashboard
+ * bringing analytics up with the shared key overrides a bare
+ * `analyticsPlugin()`, whichever order they registered in.
+ *
+ * "Whichever order" is what the `!== undefined` buys, and it is the whole
+ * reason each option is applied conditionally rather than assigned straight
+ * through. Both plugins forward their options here and an application
+ * configures whichever of the two it thinks of as the console, so under a
+ * plain assignment the answer would depend on registration order: in
+ * `apps/example`, `analyticsPlugin({ credential })` runs after
+ * `dashboardPlugin({ authorize })` and would have wiped the predicate,
+ * shutting the console it was registered to open. A call that carries a value
+ * wins; a bare call is a no-op against auth rather than a silent disarm.
+ * Turning a door off means not registering the plugin, or passing the empty
+ * string — never omitting the option.
+ *
+ * It is separate, and exported, because `setupAnalytics` cannot be called from
+ * a test: it also registers two handlers, installs a shutdown hook and kicks
+ * off a data load, none of them restorable (convention 9).
+ */
+export function applyAnalyticsAuth(options: AnalyticsAuthOptions): void {
+  if (options.credential !== undefined) {
+    setAnalyticsCredential(options.credential)
+  }
+  if (options.authorize !== undefined) setAnalyticsAuthorize(options.authorize)
+}
+
+export function setupAnalytics(options: AnalyticsAuthOptions = {}) {
+  applyAnalyticsAuth(options)
+
+  // 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()