@bakery-framework/plugin-dashboard 2.0.0-alpha.4 → 2.0.0-alpha.6

package/src/endpoints/database.ts

@@ -1,10 +1,22 @@
-import { getElapsed } from '@bakery-framework/core/logger'
-import { processBody } from '@bakery-framework/core/utils'
 import type { JsonResponseData } from '@bakery-framework/core/utils/common'
-import { is, Try } from '@bakery-framework/core/utils/common'
+import { Try } from '@bakery-framework/core/utils/common'
 import { response } from '@bakery-framework/core/utils/http'
 import { connection } from '@bakery-framework/orm/connection'
 
+/**
+ * What is left of the console's database surface: two read-only endpoints.
+ *
+ * The grid editor and the SQL prompt that used to live here are retired —
+ * `@bakery-framework/plugin-db-explorer` does the same work with an access
+ * model instead of an environment flag, and the console's Database tab is now
+ * a link to it. Gone with them: `handleQuery`, `handleExecuteAction`, the
+ * statement classifier in `sql-classify.ts`, and `DASHBOARD_ALLOW_WRITES`.
+ *
+ * The flag is not deprecated, it is *absent*. Nothing here reads it, so
+ * setting it has no effect at all — which is the honest state for a console
+ * that can no longer write.
+ */
+
 export async function handleSchema(): Promise<JsonResponseData<unknown>> {
   return await Try.return(
     async () => response.json.success('success', await connection.getSchema()),
@@ -33,179 +45,3 @@ export async function handleTableData(
     (error: any) => response.json.error(400, error.message),
   )
 }
-
-/**
- * Statements that reach outside the database itself. SQLite's `ATTACH` plus
- * `VACUUM INTO` is an arbitrary file write, which turns any dashboard session
- * (or any XSS in the dashboard origin) into host filesystem access.
- */
-const RX_OUT_OF_BAND_SQL = /\b(attach|detach|vacuum\s+into)\b/i
-
-/**
- * Writes from the dashboard need an explicit opt-in.
- *
- * This gate used to sit only in `handleQuery`, so `DELETE FROM t` typed into
- * the SQL box was refused while the grid's Delete and Truncate buttons — which
- * reach the same rows through `execute-action`, with no SQL to inspect — were
- * not. Half a control is worse than none: the production and security
- * checklists both tell operators that leaving `DASHBOARD_ALLOW_WRITES` unset
- * keeps the console read-only, and that was only ever true of one of its two
- * write paths.
- *
- * Read at call time, not at module load: tests set and restore it, and the
- * flag is a deployment decision rather than a build one.
- */
-function writesEnabled(): boolean {
-  return process.env.DASHBOARD_ALLOW_WRITES === '1'
-}
-
-export async function handleQuery(
-  req: Request,
-): Promise<JsonResponseData<unknown>> {
-  const body = await processBody(req)
-  if (!is.string(body?.sql))
-    return response.json.error(400, 'Invalid SQL query')
-
-  if (RX_OUT_OF_BAND_SQL.test(body.sql)) {
-    return response.json.error(
-      403,
-      'ATTACH / DETACH / VACUUM INTO are not permitted from the dashboard.',
-    )
-  }
-
-  const sqlLower = body.sql.trim().toLowerCase()
-  const isSelect = /^(select|with|show|describe|pragma|explain)/.test(sqlLower)
-
-  // Writes require an explicit opt-in; the browser console should not be a
-  // one-keystroke path to DROP TABLE on a production database.
-  if (!isSelect && !writesEnabled()) {
-    return response.json.error(
-      403,
-      'Write statements are disabled. Set DASHBOARD_ALLOW_WRITES=1 to enable them.',
-    )
-  }
-
-  const start = Bun.nanoseconds()
-
-  return await Try.return(
-    async () => {
-      const result = isSelect
-        ? { rows: await connection.query(body.sql).all(), isSelect: true }
-        : {
-            rows: [
-              (({ lastInsertRowid, changes }) => ({
-                lastInsertRowid,
-                changes,
-              }))(await connection.query(body.sql).run()),
-            ],
-            isSelect: false,
-          }
-
-      return response.json.success('success', {
-        ...result,
-        time: getElapsed(start),
-      })
-    },
-    (error: any) =>
-      response.json.error(400, error.message, { time: getElapsed(start) }),
-  )
-}
-
-/**
- * Every branch answers with the JSON envelope — never a `Response` — so the
- * table is typed as such. `data` stays `unknown`: these payloads are arbitrary
- * database rows, and `unknown` says that honestly where `any` would have let
- * the lie back in.
- */
-const executeActionHandlers: Record<
-  string,
-  (body: any, connection: any) => Promise<JsonResponseData<unknown>>
-> = {
-  'delete-row': async (body, connection) => {
-    if (body.rowid == null) return response.json.error(400, 'Invalid row ID')
-    return await Try.return(
-      async () => {
-        await connection.remove(body.tableName, body.rowid)
-        return response.json.success('Row deleted')
-      },
-      (e: any) => response.json.error(400, e.message),
-    )
-  },
-  truncate: async (body, connection) => {
-    return await Try.return(
-      async () => {
-        await connection.truncate(body.tableName)
-        return response.json.success('Table truncated')
-      },
-      (e: any) => response.json.error(400, e.message),
-    )
-  },
-  'insert-row': async (body, connection) => {
-    if (!body.row || typeof body.row !== 'object')
-      return response.json.error(400, 'Invalid row data')
-    return await Try.return(
-      async () => {
-        await connection.insert(body.tableName, body.row)
-        return response.json.success('Row inserted')
-      },
-      (e: any) => response.json.error(400, e.message),
-    )
-  },
-  'update-row': async (body, connection) => {
-    if (
-      !body.row ||
-      !is.object(body.row) ||
-      Array.isArray(body.row) ||
-      body.rowid == null
-    ) {
-      return response.json.error(400, 'Invalid data or row ID')
-    }
-    return await Try.return(
-      async () => {
-        await connection.update(body.tableName, body.rowid, body.row)
-        return response.json.success('Row updated')
-      },
-      (e: any) => response.json.error(400, e.message),
-    )
-  },
-  'import-csv': async (body, connection) => {
-    if (typeof body.csvContent !== 'string')
-      return response.json.error(400, 'Invalid CSV')
-    return await Try.return(
-      async () => {
-        const info = await connection.importCSV(body.tableName, body.csvContent)
-        return response.json.success(`Imported ${info.changes} rows`, {
-          info,
-        })
-      },
-      (e: any) => response.json.error(400, e.message),
-    )
-  },
-}
-
-export async function handleExecuteAction(
-  req: Request,
-): Promise<JsonResponseData<unknown>> {
-  // Every entry in `executeActionHandlers` writes — truncate and delete-row
-  // destroy data outright — so the gate covers the endpoint rather than being
-  // repeated per action. Checked before the body is even read.
-  if (!writesEnabled()) {
-    return response.json.error(
-      403,
-      'Dashboard writes are disabled. Set DASHBOARD_ALLOW_WRITES=1 to enable them.',
-    )
-  }
-
-  const body = await processBody(req)
-  const { action, tableName } = body || {}
-
-  if (!is.string(tableName) || !/^[a-zA-Z0-9_]+$/.test(tableName)) {
-    return response.json.error(400, 'Invalid table name')
-  }
-
-  const handler = executeActionHandlers[action]
-  if (handler) {
-    return await handler(body, connection)
-  }
-  return response.json.error(400, 'Unknown action')
-}

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,22 +16,17 @@ 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'
-import {
-  handleExecuteAction,
-  handleQuery,
-  handleSchema,
-  handleTableData,
-} from './endpoints/database'
+// 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 { handleSchema, handleTableData } from './endpoints/database'
 import {
   handleDeleteSession,
   handleGetSessions,
@@ -87,28 +82,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 +169,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)
@@ -194,9 +204,14 @@ async function checkAuthMiddleware(req: Request, path: string) {
  *
  * Necessary but **not sufficient on its own**. `SAFE_METHODS` exempts GET, and
  * `processBody` reads a GET's query string as the body, so a plain
- * `<img src="/api/_dashboard/execute-action?action=truncate&tableName=…">`
- * sails past this guard. The mutating keys in the table below are
- * method-qualified for exactly that reason; neither half closes the hole alone.
+ * `<img src="/api/_dashboard/sessions/delete?id=victim">` sails past this
+ * guard. The mutating keys in the table below are method-qualified for exactly
+ * that reason; neither half closes the hole alone.
+ *
+ * The example used to be `execute-action?action=truncate`, which was the worst
+ * of them — a link that emptied a table. That endpoint is gone with the grid
+ * editor, and the two session routes are what is left to protect. The hazard
+ * is unchanged; only the blast radius shrank.
  */
 function checkCsrfMiddleware(req: Request, url: URL): DashboardResponse | null {
   const reason = checkCsrf(req, url)
@@ -228,8 +243,6 @@ const dashboardRoutes = {
   'POST /api/_dashboard/sessions/update': req => handleUpdateSession(req),
   '/api/_dashboard/schema': () => handleSchema(),
   '/api/_dashboard/table-data': (_req, url) => handleTableData(url),
-  'POST /api/_dashboard/query': req => handleQuery(req),
-  'POST /api/_dashboard/execute-action': req => handleExecuteAction(req),
 } satisfies PluginRouteTable
 
 const dispatchDashboardRoute = routeTable(dashboardRoutes)
@@ -264,5 +277,24 @@ export async function handleDashboardRequest(
   const csrfBlock = checkCsrfMiddleware(req, url)
   if (csrfBlock) return csrfBlock
 
-  return dispatchDashboardRoute(req, url)
+  const result = await dispatchDashboardRoute(req, url)
+  if (result) return result
+
+  // `dispatch` answers `null` for a path no key matched, and a handler
+  // returning `null` means "not mine" — which core turns into **204 No
+  // Content**. Every unmatched request under this namespace therefore answered
+  // 204: a status that reads as success and carries nothing.
+  //
+  // Retiring the write endpoints is what made that matter. A script still
+  // posting to `/api/_dashboard/execute-action` was told 204, took it for
+  // success, and silently changed nothing. For a route that has been deleted
+  // that is the worst available answer.
+  //
+  // **Only under `/api/`, and that boundary is load-bearing.** The stylesheet
+  // is served by `mountRoutes`, not by a key in the table above, so `null` is
+  // precisely how `/_dashboard/style.css` *falls through* to the static
+  // pipeline. A blanket 404 here claims it and the console loads unstyled —
+  // which is what happened when this was first written without the condition.
+  if (path.startsWith('/api/')) return response.error('Not Found', 404)
+  return null
 }

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
-  }
-}