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

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@bakery-framework/plugin-db-explorer",
+  "version": "2.0.0-alpha.11",
+  "description": "Bakery database explorer plugin — browse and edit rows — no raw SQL, no DDL.",
+  "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.11",
+    "@bakery-framework/orm": "^2.0.0-alpha.11"
+  },
+  "engines": {
+    "bun": ">=1.4.0"
+  }
+}

package/src/access.ts

@@ -0,0 +1,188 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import {
+  credentialMatches,
+  readCredential,
+} from '@bakery-framework/core/utils/http'
+
+/**
+ * Who may do what in the explorer.
+ *
+ * The explorer used to be read-only by construction, so a boolean answered the
+ * whole question. It edits rows now, and "may this request in" and "may this
+ * request *write*" are different questions — so the predicate returns a level
+ * rather than a yes.
+ *
+ * Two doors, and an application may use either or both:
+ *
+ *   - `users` — named credentials, for people and scripts that have no session
+ *     (an on-call engineer with a key, a seeding job).
+ *   - `authorize` — a predicate over the request, for applications that already
+ *     know who their users are and would rather not keep a second list.
+ *
+ * Either can admit and the **higher** level wins, because they answer about the
+ * same caller: a session admin presenting a read-only key is still an admin.
+ *
+ * Everything fails closed. Nothing configured admits nobody — the same default
+ * the read-only explorer had, and the reason there is no `writes: true` flag to
+ * leave set by accident.
+ *
+ * This deliberately does not reuse core's `isAuthorized`, which is boolean and
+ * stays correct for the dashboard and analytics. It copies its discipline
+ * instead: an exact match, never a truthy one, and a throw is a denial.
+ */
+
+/** What a caller may do. Ordered: `write` implies `read`. */
+export type Access = 'read' | 'write'
+
+/**
+ * An application's own access check. Return `'write'`, `'read'`, or `false`.
+ *
+ * Anything else — including `true` — is a denial. The predicate is application
+ * code and this return type is only advice; an untyped or transpiled one can
+ * hand back anything, and admission is the expensive direction to get wrong.
+ */
+export type AccessFn = (
+  req: Request,
+) => Access | false | Promise<Access | false>
+
+export interface ExplorerUser {
+  /** Presented as `x-db-key`, a Bearer token, or `?db-key=` on a read. */
+  credential: string
+  access: Access
+}
+
+/** Named because a log line saying which key was used beats one saying "a key". */
+export type ExplorerUsers = Record<string, ExplorerUser>
+
+const DB_KEY = 'db-key'
+
+/** Methods that cannot change state, and may therefore carry a URL credential. */
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS'])
+
+const RANK: Record<Access, number> = { read: 1, write: 2 }
+
+/** The higher of two grants, or whichever is present. */
+function higher(a: Access | false, b: Access | false): Access | false {
+  if (!a) return b
+  if (!b) return a
+  return RANK[a] >= RANK[b] ? a : b
+}
+
+/**
+ * The credential this request presents, or `null`.
+ *
+ * Core's `readCredential` accepts three forms — `x-db-key`, a Bearer token, and
+ * `?db-key=` — and the query form is deliberate there: a human opening a URL
+ * cannot set a header.
+ *
+ * **On a state-changing request the query form is refused.** A credential in a
+ * URL is what makes a cross-site write possible: the browser will send it
+ * because it is in the link, and `checkCsrf` — which is an `Origin` check, not
+ * a token — passes when `Origin` is absent or literally `"null"`, as it is from
+ * a sandboxed iframe or some redirect chains. Requiring a header for writes
+ * means the caller had to run script on this origin.
+ */
+function presentedKey(req: Request): string | null {
+  const presented = readCredential(req, DB_KEY)
+  if (presented === null) return null
+  if (SAFE_METHODS.has(req.method)) return presented
+
+  // `readCredential` prefers header, then Bearer, then the query — so if
+  // neither header is present, the value it returned came from the URL.
+  const fromHeader =
+    req.headers.has(`x-${DB_KEY}`) || req.headers.has('authorization')
+  return fromHeader ? presented : null
+}
+
+/**
+ * The best level any configured user grants this request.
+ *
+ * **Every entry is compared, with no early exit.** Each comparison is constant
+ * time (core's `credentialMatches`), and stopping at the first match would make
+ * the response time depend on where in the map the matching key sits — which
+ * leaks the position of a valid key over enough samples.
+ */
+export function accessFromUsers(
+  req: Request,
+  users: ExplorerUsers | undefined,
+): Access | false {
+  if (!users) return false
+
+  const presented = presentedKey(req)
+  if (!presented) return false
+
+  let granted: Access | false = false
+  for (const user of Object.values(users)) {
+    if (credentialMatches(user.credential, presented)) {
+      granted = higher(granted, user.access)
+    }
+  }
+  return granted
+}
+
+/** The predicate's answer, with anything that is not an exact level denied. */
+export async function accessFromPredicate(
+  req: Request,
+  authorize: AccessFn | undefined,
+): Promise<Access | false> {
+  if (!authorize) return false
+
+  try {
+    const answer = await authorize(req)
+    // `=== `, never truthiness. `true` is a denial here on purpose: a predicate
+    // written against the old boolean API means "let them in" and cannot mean
+    // "let them write", and guessing which is exactly the mistake this type
+    // exists to prevent.
+    return answer === 'write' || answer === 'read' ? answer : false
+  } catch {
+    // An access check that errors is indeterminate, and indeterminate is a
+    // denial (convention 2).
+    return false
+  }
+}
+
+export interface AccessConfig {
+  users?: ExplorerUsers
+  authorize?: AccessFn
+}
+
+/** The caller's level: the better of the two doors, `false` if neither admits. */
+export async function resolveAccess(
+  req: Request,
+  config: AccessConfig,
+): Promise<Access | false> {
+  // Both doors are consulted even when the first admits — the predicate may
+  // grant `write` where a key granted `read`, and the caller is one person.
+  const fromKey = accessFromUsers(req, config.users)
+  const fromPredicate = await accessFromPredicate(req, config.authorize)
+  return higher(fromKey, fromPredicate)
+}
+
+/** Whether `access` permits a write. Spelled once so no call site guesses. */
+export function canWrite(access: Access | false): boolean {
+  return access === 'write'
+}
+
+/**
+ * The current request's access level, for endpoints.
+ *
+ * `AsyncLocalStorage` rather than a module variable, for the same reason
+ * `hostStore` is one in core: a module variable is shared by every in-flight
+ * request, so under any concurrency at all one caller's level would decide
+ * another caller's write. It is also cheaper than re-resolving per endpoint,
+ * which would run an application's `authorize` predicate — possibly a session
+ * lookup — twice for one request.
+ *
+ * Outside a request it is `false`, which is the safe answer rather than a
+ * crash: an endpoint reached some other way has no caller to grant anything.
+ */
+export const accessStore = new AsyncLocalStorage<Access>()
+
+export function currentAccess(): Access | false {
+  return accessStore.getStore() ?? false
+}
+
+/** Whether the *current* request may write. The check every write endpoint makes. */
+export function currentCanWrite(): boolean {
+  return canWrite(currentAccess())
+}

package/src/client/api.ts

@@ -0,0 +1,279 @@
+/**
+ * Every request this client makes, and nothing that renders.
+ *
+ * The rule that keeps the grid's complexity down is mechanical: **no function
+ * both fetches and renders.** These return data or throw `ApiError`; the DOM
+ * modules take data and return nodes. The old `renderTable` did both and scored
+ * 34 against a maximum of 25 with a fraction of this feature set.
+ */
+
+import { toWire } from '../shared/filters'
+import type { SchemaGraph, SchemaReport, TablePage } from './meta'
+import type { ViewState } from './state'
+import { PAGE_SIZE } from './state'
+
+/**
+ * A failed call, with the server's own envelope attached.
+ *
+ * `data` matters as much as the status: a 409 from `PATCH /api/_db/row` carries
+ * the row as it now stands, which is what makes *Keep mine / Take theirs*
+ * possible rather than "please try again".
+ */
+export class ApiError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+    readonly data: unknown,
+  ) {
+    super(message)
+    this.name = 'ApiError'
+  }
+}
+
+/**
+ * What to show a user when a call threw.
+ *
+ * Here rather than in `dom.ts` because the thing it knows about is `ApiError`,
+ * whose `message` is the server's own sentence from the envelope — the reason
+ * a failed write reads as "row was modified by someone else" instead of
+ * "Request failed (409)". `String(error)` is the fallback for the two throws
+ * that are not ours: an abort and a network failure.
+ *
+ * There used to be three of these — one exported from `bulk.ts`, a private
+ * near-copy in `save.ts`, and a third inlined at the `notify` call in
+ * `csv-commit.ts` — so improving the wording in one left the other two alone.
+ */
+export function messageOf(error: unknown): string {
+  const api = error as Partial<ApiError>
+  return api?.message ?? String(error)
+}
+
+const KEY_STORAGE = '__db_key'
+const KEY_PARAM = 'db-key'
+
+/**
+ * Take a `?db-key=` out of the address bar and keep it for the session.
+ *
+ * A human opening a link cannot set a header, so the credential arrives in the
+ * URL; leaving it there puts it in history, in the referrer of every outbound
+ * link, and in a screenshot. It is moved to `sessionStorage` and the URL is
+ * rewritten before anything else runs.
+ */
+export function adoptUrlKey(): void {
+  const url = new URL(location.href)
+  const key = url.searchParams.get(KEY_PARAM)
+  if (!key) return
+  sessionStorage.setItem(KEY_STORAGE, key)
+  url.searchParams.delete(KEY_PARAM)
+  history.replaceState(null, '', url)
+}
+
+/**
+ * The credential as a **header**.
+ *
+ * Never as a query parameter on a write: `access.ts` refuses a URL credential
+ * on any non-safe method, because a link is something a cross-site page can
+ * make the browser follow and `checkCsrf` passes when `Origin` is absent.
+ */
+function keyHeaders(): Record<string, string> {
+  const key = sessionStorage.getItem(KEY_STORAGE)
+  return key ? { 'x-db-key': key } : {}
+}
+
+interface Envelope {
+  status?: number
+  message?: string
+  data?: unknown
+  /** Milliseconds the server spent, filled in by `router.ts`. */
+  time?: number
+}
+
+/**
+ * The data, plus what the server said it cost.
+ *
+ * `time` is the envelope's own field — `router.ts` fills it from `getElapsed`,
+ * so it is the server's measurement of its own work rather than a round trip
+ * timed in the browser. The status bar shows it, which is the one honest number
+ * available for "why is this slow": a filter that cannot use an index shows up
+ * here immediately.
+ */
+interface Timed<T> {
+  data: T
+  ms: number
+}
+
+async function unwrapEnvelope<T>(res: Response): Promise<Timed<T>> {
+  const body = (await res.json().catch(() => null)) as Envelope | null
+  const status = body?.status ?? res.status
+  if (!body || status < 200 || status >= 300) {
+    throw new ApiError(
+      body?.message || `Request failed (${status})`,
+      status,
+      body?.data,
+    )
+  }
+  return { data: body.data as T, ms: body.time ?? 0 }
+}
+
+async function unwrap<T>(res: Response): Promise<T> {
+  return (await unwrapEnvelope<T>(res)).data
+}
+
+async function apiGet<T>(
+  path: string,
+  params?: Record<string, string>,
+  signal?: AbortSignal,
+): Promise<T> {
+  const query = params ? `?${new URLSearchParams(params)}` : ''
+  const res = await fetch(`/api/_db/${path}${query}`, {
+    headers: keyHeaders(),
+    signal,
+  })
+  return await unwrap<T>(res)
+}
+
+async function apiSend<T>(
+  method: 'POST' | 'PATCH' | 'DELETE',
+  path: string,
+  body: unknown,
+  signal?: AbortSignal,
+): Promise<T> {
+  const res = await fetch(`/api/_db/${path}`, {
+    method,
+    headers: { ...keyHeaders(), 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+    signal,
+  })
+  return await unwrap<T>(res)
+}
+
+export async function fetchSchema(): Promise<SchemaReport> {
+  return await apiGet<SchemaReport>('schema')
+}
+
+export async function fetchGraph(): Promise<SchemaGraph> {
+  return await apiGet<SchemaGraph>('graph')
+}
+
+/**
+ * One page of a table, with the server's own timing.
+ *
+ * **`filters` carries an operator now.** It used to be a bare column→substring
+ * record, which meant `col LIKE '%value%'` and nothing else — so a filter could
+ * narrow a page but could never *name* a row, `1` matching `11` and `21`. With
+ * `eq` in the vocabulary it can, which is what removed `ViewState.focus` and
+ * turned a foreign-key jump into an ordinary filter.
+ *
+ * The scalar form is still what the endpoint accepts from anyone else; `toWire`
+ * always sends the object form from here.
+ */
+export async function fetchPage(view: ViewState): Promise<Timed<TablePage>> {
+  const params: Record<string, string> = {
+    tableName: view.table,
+    page: String(view.page),
+    pageSize: String(PAGE_SIZE),
+    sortOrder: view.sortOrder,
+  }
+  if (view.sortBy) params.sortBy = view.sortBy
+  const wire = toWire(view.filters)
+  if (Object.keys(wire).length) params.filters = JSON.stringify(wire)
+
+  const query = `?${new URLSearchParams(params)}`
+  const res = await fetch(`/api/_db/table-data${query}`, {
+    headers: keyHeaders(),
+  })
+  return await unwrapEnvelope<TablePage>(res)
+}
+
+export interface LookupRef {
+  table: string
+  key: Record<string, unknown>
+}
+
+export interface LookupResult {
+  table: string
+  key: Record<string, unknown>
+  row: Record<string, unknown> | null
+}
+
+/** Bounded at 200 by `policy.ts`; `fk.ts` never sends more than a page's worth. */
+export async function lookupRefs(
+  refs: LookupRef[],
+  signal?: AbortSignal,
+): Promise<LookupResult[]> {
+  const data = await apiSend<{ rows: LookupResult[] }>(
+    'POST',
+    'lookup',
+    { refs },
+    signal,
+  )
+  return data.rows ?? []
+}
+
+interface UpdateResult {
+  changed: number
+  row: Record<string, unknown> | null
+}
+
+export async function patchRow(payload: {
+  table: string
+  key: Record<string, unknown>
+  set: Record<string, unknown>
+  expect: Record<string, unknown>
+  force?: boolean
+}): Promise<UpdateResult> {
+  return await apiSend<UpdateResult>('PATCH', 'row', payload)
+}
+
+interface BulkResult {
+  changed: number
+  conflicts: { index: number; key: Record<string, unknown>; reason: string }[]
+}
+
+export async function bulkEdit(payload: {
+  table: string
+  edits: { key: Record<string, unknown>; set: Record<string, unknown> }[]
+  dryRun?: boolean
+}): Promise<BulkResult> {
+  return await apiSend<BulkResult>('POST', 'rows/bulk', payload)
+}
+
+interface DeleteResult {
+  deleted: number
+  conflicts: { index: number; key: Record<string, unknown>; reason: string }[]
+}
+
+export async function deleteRows(payload: {
+  table: string
+  keys: Record<string, unknown>[]
+  dryRun?: boolean
+}): Promise<DeleteResult> {
+  return await apiSend<DeleteResult>('DELETE', 'rows', payload)
+}
+
+interface InsertResult {
+  inserted: number
+  rows?: Record<string, unknown>[]
+}
+
+export async function insertRows(payload: {
+  table: string
+  rows: Record<string, unknown>[]
+}): Promise<InsertResult> {
+  return await apiSend<InsertResult>('POST', 'rows', payload)
+}
+
+export interface ImportResult {
+  inserted: number
+  skipped: number
+  errors: { row: number; column: string; code: string; message: string }[]
+}
+
+export async function importRows(payload: {
+  table: string
+  rows: Record<string, unknown>[]
+  onBadRow: 'stop' | 'skip'
+  dryRun?: boolean
+}): Promise<ImportResult> {
+  return await apiSend<ImportResult>('POST', 'import', payload)
+}