@bakery-framework/plugin-dashboard 2.0.0-alpha.3 → 2.0.0-alpha.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bakery-framework/plugin-dashboard",
-  "version": "2.0.0-alpha.3",
+  "version": "2.0.0-alpha.5",
   "description": "Bakery dashboard plugin.",
   "keywords": [
     "bakery",
@@ -33,8 +33,9 @@
     "!src/tests"
   ],
   "dependencies": {
-    "@bakery-framework/core": "^2.0.0-alpha.3",
-    "@bakery-framework/orm": "^2.0.0-alpha.3"
+    "@bakery-framework/core": "^2.0.0-alpha.5",
+    "@bakery-framework/orm": "^2.0.0-alpha.5",
+    "@bakery-framework/plugin-analytics": "^2.0.0-alpha.5"
   },
   "engines": {
     "bun": ">=1.3.14"

package/src/index.ts

@@ -1,7 +1,13 @@
 import { definePlugin } from '@bakery-framework/core/plugins'
-import type { AuthorizeFn } from './authorize'
+import type { AuthorizeFn } from '@bakery-framework/core/utils/http'
 
-export type { AuthorizeFn } from './authorize'
+/**
+ * Re-exported so the plugin's public surface is unchanged by the guard moving
+ * into core. It is the same type either way — an app that imported it from here
+ * keeps working, and one that reaches for `@bakery-framework/core/utils/http`
+ * directly gets the identical declaration rather than a structural twin.
+ */
+export type { AuthorizeFn } from '@bakery-framework/core/utils/http'
 
 export interface DashboardPluginOptions {
   /**
@@ -24,10 +30,43 @@ export interface DashboardPluginOptions {
    *
    * Omitted, access is limited to loopback in development and denied in
    * production, so an unconfigured console is never exposed.
+   *
+   * Handed straight to `@bakery-framework/plugin-analytics`, which owns the
+   * door for both surfaces — so this predicate also admits to
+   * `/api/_analytics/stats` and the `/_analytics_ws` socket the console reads.
    */
   authorize?: AuthorizeFn
+
+  /**
+   * A shared access key, typically from the environment:
+   *
+   * ```ts
+   * dashboardPlugin({ 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 path is off — it never means open. Composes with `authorize`: either
+   * admits.
+   *
+   * It is the *analytics* key, not a second one: the console delegates its
+   * authorization to `@bakery-framework/plugin-analytics`, so configuring it
+   * here and configuring it on `analyticsPlugin` are the same act. Set it on
+   * either plugin — a bare call never clears what the other one set.
+   */
+  credential?: string
 }
 
+/**
+ * The operator console at `/_dashboard`.
+ *
+ * `@bakery-framework/plugin-analytics` is a hard dependency, not an optional
+ * companion: the console renders analytics, its client calls
+ * `/api/_analytics/reset` and opens `/_analytics_ws`, and registering the
+ * dashboard brings analytics' handlers up so those endpoints exist. It follows
+ * that they share one door rather than two — see `authorize` and `credential`
+ * above.
+ */
 export default function dashboardPlugin(options: DashboardPluginOptions = {}) {
   const enabled = options.enabled ?? true
 
@@ -36,7 +75,10 @@ export default function dashboardPlugin(options: DashboardPluginOptions = {}) {
     async setup() {
       if (!enabled) return
       const { setupDashboard } = await import('./setup')
-      await setupDashboard({ authorize: options.authorize })
+      await setupDashboard({
+        authorize: options.authorize,
+        credential: options.credential,
+      })
     },
   })
 }

package/src/setup.ts

@@ -16,16 +16,16 @@ import {
 import type { JsonResponseData } from '@bakery-framework/core/utils/common'
 import { Try } from '@bakery-framework/core/utils/common'
 import {
+  type AuthorizeFn,
   checkCsrf,
   injectIfHtml,
+  resolveAuthorize,
   response,
 } from '@bakery-framework/core/utils/http'
-import {
-  type AuthorizeFn,
-  defaultAuthorize,
-  isAuthorized,
-  resolveAuthorize,
-} from './authorize'
+// The console's door is analytics'. This is the one plugin-to-plugin edge in
+// the tree, allow-listed by name in `tests/conventions.test.ts`.
+import { setupAnalytics } from '@bakery-framework/plugin-analytics/setup'
+import { isAnalyticsAuthorized } from '@bakery-framework/plugin-analytics/stats'
 import {
   handleExecuteAction,
   handleQuery,
@@ -87,28 +87,29 @@ export class DashboardHandler extends Handler {
   }
 }
 
-let authorize: AuthorizeFn = defaultAuthorize
-
 /**
- * Test seam for the module-level predicate, symmetric with `__setTestDb` in
- * `@bakery-framework/orm` and `__setTestConfig` in core.
+ * The console holds no authorization state of its own — there is no
+ * `__setTestAuthorize` seam here any more, because there is nothing local to
+ * seam. Both options land in analytics, and a test drives the door with
+ * `setAnalyticsAuthorize` / `setAnalyticsCredential` from
+ * `@bakery-framework/plugin-analytics/stats`, which is the same state the
+ * request guard reads.
  *
- * `setupDashboard` is the only other way to set it, and it also mounts routes,
- * registers the handler at priority 120 and installs a global log callback —
- * three process-global mutations, none of them restorable. A test that only
- * needs the request pipeline sets the predicate directly and puts it back in
- * `afterAll`. Always pair with `__resetTestAuthorize()`.
+ * `resolveAuthorize` still runs here rather than in analytics, and that
+ * asymmetry is deliberate. Analytics on its own is closed until configured;
+ * the console keeps its documented default of loopback-in-development,
+ * because `bun create bakery` scaffolds a bare `dashboardPlugin()` and a
+ * console that 404s on the first `bun run dev` is the wrong first impression.
+ * Forwarding `defaultAuthorize` can only ever narrow — it denies in
+ * production and admits nothing but this machine in development.
  */
-export function __setTestAuthorize(fn: AuthorizeFn): void {
-  authorize = fn
-}
-
-export function __resetTestAuthorize(): void {
-  authorize = defaultAuthorize
-}
-
-export function setupDashboard(options: { authorize?: AuthorizeFn } = {}) {
-  authorize = resolveAuthorize(options.authorize)
+export function setupDashboard(
+  options: { authorize?: AuthorizeFn; credential?: string } = {},
+) {
+  setupAnalytics({
+    authorize: resolveAuthorize(options.authorize),
+    credential: options.credential,
+  })
 
   setLogCallback(entry => {
     // Broadcast to the registry LiveReloadHandler actually populates. This used
@@ -173,12 +174,26 @@ async function handleJsAsset() {
   return response.type(bundleResult.content, 'text/javascript')
 }
 
+/**
+ * One door, and it is analytics'. `isAnalyticsAuthorized` reads the same
+ * credential and the same predicate that gate `/api/_analytics/stats` and the
+ * `/_analytics_ws` socket — which the console's own client calls, so a console
+ * admitted by a different key than the data it renders would be half-open by
+ * construction.
+ *
+ * The 401/404 split is the console's and stays here: an API path says
+ * "Unauthorized" because a caller with a key needs to know its key was
+ * refused, while a page says "Not Found" because a 401 on the shell confirms
+ * to anyone probing that a console is mounted at this path. Analytics makes
+ * the same distinction along a different axis (armed → 401, unconfigured →
+ * 404); neither is a substitute for the other.
+ */
 async function checkAuthMiddleware(req: Request, path: string) {
   // Styling and script for the console are not secrets, and letting them
   // through keeps an unauthorised response from rendering unstyled.
   if (/\.(css|js)$/.test(path)) return null
 
-  if (await isAuthorized(authorize, req)) return null
+  if (await isAnalyticsAuthorized(req)) return null
 
   return path.startsWith('/api/')
     ? response.error('Unauthorized', 401)

package/src/authorize.ts

@@ -1,76 +0,0 @@
-import { getClientIp } from '@bakery-framework/core/utils/http'
-
-/**
- * Decides whether a request may use the console.
- *
- * The dashboard used to run its own identity system: a shared `DASHPASS`
- * secret, a login form, a session flag, a constant-time compare and a
- * failed-attempt backoff map. That is a lot of security-sensitive surface for
- * a framework to own, and it composed with nothing — an app with real users
- * and roles still had to hand out a second, shared password.
- *
- * So the dashboard no longer authenticates anyone. The host application, which
- * already knows who its users are, supplies a predicate.
- */
-export type AuthorizeFn = (req: Request) => boolean | Promise<boolean>
-
-/**
- * Addresses only. `'localhost'` used to be a member because the request's
- * *hostname* was compared against this set as well — see below for why that is
- * gone. A peer address is never the string `localhost`, and accepting it would
- * mean an `X-Forwarded-For: localhost` counted as loopback under `trustProxy`.
- */
-const LOOPBACK = new Set(['127.0.0.1', '::1', '::ffff:127.0.0.1'])
-
-/** True when the request came from this machine. */
-export function isLoopback(req: Request): boolean {
-  // The peer address is the only evidence here the client does not choose.
-  // This used to fall back to `new URL(req.url).hostname`, which Bun builds
-  // from the client's own `Host` header — and `DEFAULT_HOST` is 0.0.0.0, so a
-  // dev server listens on every interface. Any peer on the LAN could send
-  // `Host: localhost` and be handed the database browser.
-  //
-  // getClientIp reads config and the live server, either of which may be
-  // absent (tests, early boot). An address that cannot be determined is
-  // indeterminate, and an indeterminate answer is a denial — not a reason to
-  // consult something the requester controls.
-  let ip = ''
-  try {
-    ip = getClientIp(req)
-  } catch {
-    // See above: no server and no config means no evidence, which is a denial.
-    ip = ''
-  }
-
-  return LOOPBACK.has(ip)
-}
-
-/**
- * Fail closed. With no predicate configured the console is reachable only from
- * loopback in development, and from nowhere in production — so forgetting to
- * configure it cannot expose a database browser to the internet.
- */
-export function defaultAuthorize(req: Request): boolean {
-  if (!import.meta.env.DEV) return false
-  return isLoopback(req)
-}
-
-export function resolveAuthorize(authorize?: AuthorizeFn): AuthorizeFn {
-  return authorize ?? defaultAuthorize
-}
-
-/**
- * Run a predicate without letting a throwing one grant access.
- */
-export async function isAuthorized(
-  authorize: AuthorizeFn,
-  req: Request,
-): Promise<boolean> {
-  try {
-    return Boolean(await authorize(req))
-  } catch {
-    // An authorization check that errors is indeterminate, and an
-    // indeterminate answer is a denial.
-    return false
-  }
-}