@bakery-framework/plugin-db-explorer 2.0.0-alpha.2

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@bakery-framework/plugin-db-explorer",
+  "version": "2.0.0-alpha.2",
+  "description": "Bakery database explorer plugin — read-only browsing of the app database.",
+  "keywords": [
+    "bakery",
+    "bun",
+    "database",
+    "explorer",
+    "plugin"
+  ],
+  "author": "obillekyle",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/obillekyle/bakery.git",
+    "directory": "packages/plugins/db-explorer"
+  },
+  "homepage": "https://bakery.okyle.dev",
+  "bugs": "https://github.com/obillekyle/bakery/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/tests"
+  ],
+  "dependencies": {
+    "@bakery-framework/core": "^2.0.0-alpha.2",
+    "@bakery-framework/orm": "^2.0.0-alpha.2"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
+  }
+}

package/src/authorize.ts

@@ -0,0 +1,82 @@
+import {
+  getClientIp,
+  requestHasCredential,
+} from '@bakery-framework/core/utils/http'
+
+/**
+ * Decides whether a request may use the explorer.
+ *
+ * Same design as the dashboard's guard, for the same reason: the explorer
+ * authenticates nobody itself. The host application, which already knows who
+ * its users are, supplies a predicate; without one, access is loopback-only
+ * in development and denied outright in production, so an unconfigured
+ * explorer is never exposed.
+ */
+export type AuthorizeFn = (req: Request) => boolean | Promise<boolean>
+
+/**
+ * Addresses only, never hostnames: a peer address is not the string
+ * `localhost`, and matching the request's hostname would trust a header the
+ * client chooses (`Host: localhost` from anywhere on the LAN, with the dev
+ * server listening on 0.0.0.0).
+ */
+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.
+  // 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 per convention 2 an indeterminate answer is a denial —
+  // not a reason to consult something the requester controls.
+  let ip = ''
+  try {
+    ip = getClientIp(req)
+  } catch {
+    return false
+  }
+  return LOOPBACK.has(ip)
+}
+
+/**
+ * The default: loopback in dev, nothing in prod. `import.meta.env.PROD` read
+ * at call time — the flag is process state, and tests flip it.
+ */
+export function defaultAuthorize(req: Request): boolean {
+  if (import.meta.env.PROD) return false
+  return isLoopback(req)
+}
+
+export function resolveAuthorize(fn?: AuthorizeFn): AuthorizeFn {
+  return fn ?? defaultAuthorize
+}
+
+/**
+ * Guard semantics per convention 2: the *authorizer* may throw or hang-fail;
+ * the answer to any indeterminate state is denial.
+ */
+export async function isAuthorized(
+  authorize: AuthorizeFn,
+  req: Request,
+): Promise<boolean> {
+  try {
+    return (await authorize(req)) === true
+  } catch {
+    // A predicate that throws is indeterminate, and indeterminate is denied.
+    return false
+  }
+}
+
+/**
+ * Shared-credential access: `dbExplorerPlugin({ credential: import.meta.env
+ * .DB_EXPLORER_KEY })`, presented as `x-db-key`, a Bearer token, or a
+ * one-time `?db-key=` query the client strips from the URL. The comparison
+ * lives in core (`requestHasCredential`) — one copy, shared with analytics;
+ * this only names the key, `db-key`.
+ */
+export function credentialMatches(
+  credential: string | undefined,
+  req: Request,
+): boolean {
+  return requestHasCredential(req, credential, 'db-key')
+}

package/src/client.ts

@@ -0,0 +1,193 @@
+/**
+ * The explorer UI: a table list, a row grid with paging and sorting, nothing
+ * else. Compiled per request in dev and cached like the dashboard's client;
+ * kept deliberately small — this file is the entire browser side.
+ */
+
+type SchemaTable = { name: string; rowCount?: number }
+
+type TablePage = {
+  rows: Record<string, unknown>[]
+  totalRows?: number
+  totalPages?: number
+}
+
+const app = document.getElementById('app')!
+
+let currentTable = ''
+let currentPage = 1
+let sortBy: string | null = null
+let sortOrder: 'ASC' | 'DESC' = 'ASC'
+const PAGE_SIZE = 50
+
+// A ?key= opened in the browser is kept for API calls and scrubbed from the
+// URL (and so from history) immediately.
+const urlKey = new URLSearchParams(location.search).get('db-key')
+if (urlKey) {
+  sessionStorage.setItem('__db_key', urlKey)
+  const clean = new URL(location.href)
+  clean.searchParams.delete('db-key')
+  history.replaceState(null, '', clean)
+}
+
+function keyHeaders(): Record<string, string> {
+  const key = sessionStorage.getItem('__db_key')
+  return key ? { 'x-db-key': key } : {}
+}
+
+async function api<T>(path: string): Promise<T> {
+  const res = await fetch(`/api/_db/${path}`, { headers: keyHeaders() })
+  const json = await res.json()
+  if (json.status < 200 || json.status >= 300) {
+    throw new Error(json.message || `Request failed (${json.status})`)
+  }
+  return json.data as T
+}
+
+function el(tag: string, cls?: string, text?: string): HTMLElement {
+  const node = document.createElement(tag)
+  if (cls) node.className = cls
+  if (text !== undefined) node.textContent = text
+  return node
+}
+
+function renderShell(tables: string[]) {
+  app.replaceChildren()
+
+  const side = el('nav', 'side')
+  side.appendChild(el('h1', 'brand', 'db explorer'))
+  side.appendChild(el('p', 'note', 'read-only'))
+
+  for (const name of tables.sort()) {
+    const btn = el('button', 'table-btn', name)
+    btn.addEventListener('click', () => {
+      currentTable = name
+      currentPage = 1
+      sortBy = null
+      void renderTable()
+      side
+        .querySelectorAll('.table-btn')
+        .forEach(b => b.classList.toggle('active', b.textContent === name))
+    })
+    side.appendChild(btn)
+  }
+
+  const main = el('main', 'main')
+  main.id = 'main'
+  main.appendChild(el('p', 'note', 'Pick a table.'))
+
+  app.append(side, main)
+}
+
+async function renderTable() {
+  const main = document.getElementById('main')!
+  main.replaceChildren(el('p', 'note', `loading ${currentTable}…`))
+
+  const params = new URLSearchParams({
+    tableName: currentTable,
+    page: String(currentPage),
+    pageSize: String(PAGE_SIZE),
+    sortOrder,
+  })
+  if (sortBy) params.set('sortBy', sortBy)
+
+  let data: TablePage
+  try {
+    data = await api<TablePage>(`table-data?${params}`)
+  } catch (error) {
+    main.replaceChildren(el('p', 'error', String(error)))
+    return
+  }
+
+  const rows = data.rows ?? []
+  main.replaceChildren()
+
+  const head = el('header', 'table-head')
+  head.appendChild(el('h2', undefined, currentTable))
+  const meta = el('span', 'note')
+  meta.textContent =
+    data.totalRows !== undefined
+      ? `${data.totalRows} rows · page ${currentPage}${data.totalPages ? ` / ${data.totalPages}` : ''}`
+      : `page ${currentPage}`
+  head.appendChild(meta)
+  main.appendChild(head)
+
+  if (!rows.length) {
+    main.appendChild(el('p', 'note', 'No rows on this page.'))
+  } else {
+    const cols = Object.keys(rows[0])
+    const table = el('table', 'grid')
+    const thead = el('thead')
+    const headRow = el('tr')
+    for (const col of cols) {
+      const th = el('th', undefined, col)
+      if (col === sortBy) th.textContent += sortOrder === 'ASC' ? ' ↑' : ' ↓'
+      // rowid is in the payload but not in the sortable allow-list server-side;
+      // offering a header click that silently no-ops reads as a bug.
+      if (col === 'rowid') {
+        headRow.appendChild(th)
+        continue
+      }
+      th.addEventListener('click', () => {
+        sortOrder = sortBy === col && sortOrder === 'ASC' ? 'DESC' : 'ASC'
+        sortBy = col
+        void renderTable()
+      })
+      headRow.appendChild(th)
+    }
+    thead.appendChild(headRow)
+    table.appendChild(thead)
+
+    const tbody = el('tbody')
+    for (const row of rows) {
+      const tr = el('tr')
+      for (const col of cols) {
+        const value = row[col]
+        tr.appendChild(
+          el(
+            'td',
+            value === null ? 'null' : undefined,
+            value === null ? 'NULL' : String(value),
+          ),
+        )
+      }
+      tbody.appendChild(tr)
+    }
+    table.appendChild(tbody)
+
+    const scroller = el('div', 'scroll')
+    scroller.appendChild(table)
+    main.appendChild(scroller)
+  }
+
+  const pager = el('footer', 'pager')
+  const prev = el('button', undefined, '← prev') as HTMLButtonElement
+  prev.disabled = currentPage <= 1
+  prev.addEventListener('click', () => {
+    currentPage--
+    void renderTable()
+  })
+  const next = el('button', undefined, 'next →') as HTMLButtonElement
+  next.disabled =
+    data.totalPages !== undefined
+      ? currentPage >= data.totalPages
+      : rows.length < PAGE_SIZE
+  next.addEventListener('click', () => {
+    currentPage++
+    void renderTable()
+  })
+  pager.append(prev, next)
+  main.appendChild(pager)
+}
+
+async function boot() {
+  try {
+    // `getSchema` answers a list of table descriptors, not a keyed object.
+    const schema = await api<SchemaTable[]>('schema')
+    renderShell((schema ?? []).map(t => t.name).filter(Boolean))
+  } catch (error) {
+    app.replaceChildren(el('p', 'error', String(error)))
+  }
+}
+
+void boot()

package/src/endpoints.ts

@@ -0,0 +1,48 @@
+import type { JsonResponseData } 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'
+
+/**
+ * The explorer's whole write surface, enumerated: there is none.
+ *
+ * Both endpoints are reads, there is no raw-SQL endpoint, and no row
+ * mutations — that is the plugin's contract, not a configuration. The
+ * dashboard's `DASHBOARD_ALLOW_WRITES` gate exists because the dashboard
+ * *has* write paths to gate; the explorer removes the paths instead of
+ * gating them, so there is no flag to leave set by accident and no second
+ * write path for a gate to miss.
+ */
+
+export async function handleSchema(): Promise<JsonResponseData<unknown>> {
+  return await Try.return(
+    async () => response.json.success('success', await connection.getSchema()),
+    () => response.json.error(500, 'Failed to retrieve schema details'),
+  )
+}
+
+/** Table names the way the ORM writes them: identifier characters only. */
+const RX_TABLE_NAME = /^[a-zA-Z0-9_]+$/
+
+export async function handleTableData(
+  url: URL,
+): Promise<JsonResponseData<unknown>> {
+  const tableName = url.searchParams.get('tableName')
+  if (!tableName || !RX_TABLE_NAME.test(tableName)) {
+    return response.json.error(400, 'Invalid table name')
+  }
+
+  return await Try.return(
+    async () => {
+      const data = await connection.getData(tableName, {
+        page: Number.parseInt(url.searchParams.get('page') || '1', 10),
+        pageSize: Number.parseInt(url.searchParams.get('pageSize') || '50', 10),
+        sortBy: url.searchParams.get('sortBy'),
+        sortOrder: url.searchParams.get('sortOrder') || 'ASC',
+        filters: JSON.parse(url.searchParams.get('filters') || '{}'),
+      })
+      return response.json.success('success', data)
+    },
+    (error: any) => response.json.error(400, error.message),
+  )
+}

package/src/index.ts

@@ -0,0 +1,68 @@
+import { definePlugin } from '@bakery-framework/core/plugins'
+import type { AuthorizeFn } from './authorize'
+
+export type { AuthorizeFn } from './authorize'
+
+export interface DbExplorerPluginOptions {
+  /**
+   * Register the explorer. Defaults to true; set false to keep it out of a
+   * build entirely.
+   */
+  enabled?: boolean
+
+  /**
+   * Decide whether a request may browse the database. Return true to allow.
+   *
+   * The explorer authenticates nobody itself — the application does, because
+   * it already knows who its users are:
+   *
+   * ```ts
+   * dbExplorerPlugin({
+   *   authorize: req => req.session.get('role') === 'admin',
+   * })
+   * ```
+   *
+   * Omitted, access is loopback-only in development and denied in
+   * production, so an unconfigured explorer is never exposed.
+   */
+  authorize?: AuthorizeFn
+
+  /**
+   * A shared access key, typically from the environment:
+   *
+   * ```ts
+   * dbExplorerPlugin({ credential: import.meta.env.DB_EXPLORER_KEY })
+   * ```
+   *
+   * Presented as `Authorization: Bearer`, an `x-db-key` header, or a
+   * one-time `?key=` query for a browser (stored client-side, stripped from
+   * the URL). Checked in constant time. Unset or empty means this path is
+   * off — it never means open. Composes with `authorize`: either admits.
+   */
+  credential?: string
+}
+
+/**
+ * A read-only database browser at `/_db`: table list, rows, paging, sorting.
+ *
+ * Read-only is the contract, not a mode. There is no raw-SQL endpoint, no
+ * row mutation, and no DDL — where the dashboard gates its write paths
+ * behind `DASHBOARD_ALLOW_WRITES`, the explorer has no write paths to gate.
+ */
+export default function dbExplorerPlugin(
+  options: DbExplorerPluginOptions = {},
+) {
+  const enabled = options.enabled ?? true
+
+  return definePlugin({
+    name: 'db-explorer',
+    async setup() {
+      if (!enabled) return
+      const { setupExplorer } = await import('./setup')
+      setupExplorer({
+        authorize: options.authorize,
+        credential: options.credential,
+      })
+    },
+  })
+}

package/src/setup.ts

@@ -0,0 +1,162 @@
+import { bundleModule } from '@bakery-framework/core/compiler'
+import { Bakery } from '@bakery-framework/core/core/bakery'
+import { Handler } from '@bakery-framework/core/handlers'
+import { errorMsg } from '@bakery-framework/core/logger'
+import type { PluginRouteTable } from '@bakery-framework/core/plugins'
+import { routeTable } from '@bakery-framework/core/plugins'
+import { fs } from '@bakery-framework/core/utils'
+import { response } from '@bakery-framework/core/utils/http'
+import {
+  type AuthorizeFn,
+  credentialMatches,
+  defaultAuthorize,
+  isAuthorized,
+  resolveAuthorize,
+} from './authorize'
+import { handleSchema, handleTableData } from './endpoints'
+
+/**
+ * Where this plugin's own files live — each package that ships files anchors
+ * to its own location, never to core's (see the dashboard's `paths.ts` for
+ * the 404s that lesson cost).
+ */
+const pluginRoot: string = fs.resolve(import.meta.dir)
+
+let authorize: AuthorizeFn = defaultAuthorize
+let credential: string | undefined
+
+/**
+ * Test seam, same shape as the dashboard's: `setupExplorer` mutates process
+ * globals that cannot be restored, so tests that only need the request
+ * pipeline set the predicate directly. Always pair with the reset.
+ */
+export function __setTestAuthorize(fn: AuthorizeFn): void {
+  authorize = fn
+}
+
+export function __resetTestAuthorize(): void {
+  authorize = defaultAuthorize
+  credential = undefined
+}
+
+/** Test seam for the credential path; reset with __resetTestAuthorize. */
+export function __setTestCredential(value: string | undefined): void {
+  credential = value
+}
+
+const SHELL = `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<title>Database explorer</title>
+<style>
+  :root { color-scheme: dark; }
+  * { box-sizing: border-box; }
+  body { margin: 0; font: 14px/1.5 ui-sans-serif, system-ui, sans-serif; background: #0f1115; color: #e6e8ee; }
+  #app { display: flex; min-height: 100vh; }
+  .side { width: 220px; padding: 1rem; border-right: 1px solid #262b36; flex-shrink: 0; }
+  .brand { font-size: 1rem; margin: 0; }
+  .note { color: #9aa3b2; font-size: 0.8rem; }
+  .error { color: #ff8ba0; padding: 1rem; }
+  .table-btn { display: block; width: 100%; text-align: left; background: none; border: 0; color: #cfd6e4; padding: 0.35rem 0.5rem; border-radius: 6px; cursor: pointer; font: inherit; }
+  .table-btn:hover { background: #1a1f2b; }
+  .table-btn.active { background: #16233d; color: #cfe0ff; }
+  .main { flex: 1; padding: 1rem 1.5rem; min-width: 0; }
+  .table-head { display: flex; align-items: baseline; gap: 1rem; }
+  .table-head h2 { margin: 0.2rem 0 0.8rem; font-family: ui-monospace, monospace; font-size: 1rem; }
+  .scroll { overflow-x: auto; border: 1px solid #262b36; border-radius: 8px; }
+  .grid { border-collapse: collapse; width: 100%; font-size: 0.82rem; }
+  .grid th { text-align: left; padding: 0.45rem 0.7rem; background: #151922; cursor: pointer; white-space: nowrap; position: sticky; top: 0; }
+  .grid td { padding: 0.35rem 0.7rem; border-top: 1px solid #1e2430; font-family: ui-monospace, monospace; white-space: nowrap; max-width: 26rem; overflow: hidden; text-overflow: ellipsis; }
+  .grid td.null { color: #5b6472; font-style: italic; }
+  .pager { margin-top: 0.8rem; display: flex; gap: 0.5rem; }
+  .pager button { font: inherit; padding: 0.3rem 0.8rem; border-radius: 6px; border: 1px solid #2f6feb; background: #16233d; color: #cfe0ff; cursor: pointer; }
+  .pager button:disabled { opacity: 0.4; cursor: default; }
+</style>
+</head>
+<body>
+<div id="app"><p class="note" style="padding:1rem">loading…</p></div>
+<script type="module" src="/_db/app.js"></script>
+</body>
+</html>`
+
+let cachedClientJs: string | null = null
+
+async function handleClientJs() {
+  // PROD caches the bundle in memory; dev recompiles so edits show up.
+  if (cachedClientJs && import.meta.env.PROD) {
+    return response.type(cachedClientJs, 'text/javascript; charset=utf-8')
+  }
+
+  const built = await bundleModule(
+    fs.resolve(pluginRoot, 'client.ts') as fs.AbsolutePath,
+  )
+  if (!built.success || !built.content) {
+    return response.error(
+      `Failed to bundle explorer client: ${errorMsg(built.errors?.join('\n'))}`,
+      500,
+    )
+  }
+
+  cachedClientJs = built.content
+  return response.type(built.content, 'text/javascript; charset=utf-8')
+}
+
+/**
+ * Read-only by construction: the two data endpoints call only `getSchema`
+ * and `getData`. No raw SQL, no row mutations, no DDL — the write paths do
+ * not exist, which is a stronger property than any gate over them. The keys
+ * are method-unqualified because a bare key matches any method and every
+ * handler here is a read; there is nothing a smuggled POST could mutate,
+ * which is also why this table carries no CSRF middleware where the
+ * dashboard's must.
+ */
+const explorerRoutes = {
+  '/_db': () => response.html(SHELL),
+  '/_db/app.js': () => handleClientJs(),
+  '/api/_db/schema': () => handleSchema(),
+  '/api/_db/table-data': (_req, url) => handleTableData(url),
+} satisfies PluginRouteTable
+
+const dispatchExplorerRoute = routeTable(explorerRoutes)
+
+export class DbExplorerHandler extends Handler {
+  static canHandle(path: string) {
+    return (
+      path === '/_db' ||
+      path.startsWith('/_db/') ||
+      path === '/api/_db' ||
+      path.startsWith('/api/_db/')
+    )
+  }
+
+  static async handle(path: string, req: Request) {
+    // Styling and script are not secrets, and letting them through keeps an
+    // unauthorised response from rendering unstyled — same split as the
+    // dashboard. Everything else fails closed. Either door admits: the
+    // shared credential (constant-time, off when unset) or the predicate.
+    const admitted =
+      credentialMatches(credential, req) || (await isAuthorized(authorize, req))
+    if (!/\.(css|js)$/.test(path) && !admitted) {
+      return path.startsWith('/api/')
+        ? response.error('Unauthorized', 401)
+        : response.error('Not Found', 404)
+    }
+
+    // Dispatch keys on `url.pathname` from the request itself — the `path`
+    // argument only steers the auth split above.
+    const result = await dispatchExplorerRoute(req)
+    return result ?? response.error('Not Found', 404)
+  }
+}
+
+export function setupExplorer(
+  options: { authorize?: AuthorizeFn; credential?: string } = {},
+) {
+  authorize = resolveAuthorize(options.authorize)
+  credential = options.credential
+  // Above the content handlers, below nothing that matters: the /_db and
+  // /api/_db namespaces are reserved for framework routes (convention 10),
+  // so priority only needs to beat ApiHandler (70) for the /api half.
+  Bakery.handlers.fetch.set(DbExplorerHandler, 115)
+}