pgkiln 0.31.0 → 0.35.0

package/src/runtime/availability.ts

@@ -0,0 +1,37 @@
+// Application availability (APEX: Application Availability), migration 083.
+// Decides whether a request may use the application: everyone (available),
+// developers with a builder session in the browser (developers), the users
+// named and developers (restricted), or nobody (unavailable). Pages, file
+// downloads and REST modules ask here; PostgREST asks meta.api_check().
+import type { MessageKey } from '../i18n.ts';
+
+export type Availability = 'available' | 'developers' | 'restricted' | 'unavailable';
+
+export interface AvailabilitySettings {
+  availability?: Availability | null;
+  availability_message?: string | null;
+  availability_users?: string[] | null;
+}
+
+export interface Refusal {
+  status: 403 | 503;
+  /** the default text; the application's own message replaces it when it is unavailable or for developers only */
+  key: MessageKey;
+  message: string | null;
+  /** restricted and not signed in: sign in first */
+  signIn?: boolean;
+}
+
+/** Null when the request may go on, else why not. */
+export function availabilityRefusal(app: AvailabilitySettings, who: { username: string | null; developer: boolean }): Refusal | null {
+  const mode = app.availability ?? 'available';
+  if (mode === 'available') return null;
+  const message = app.availability_message?.trim() || null;
+  if (mode === 'unavailable') return { status: 503, key: 'app.unavailable', message };
+  if (who.developer) return null;
+  if (mode === 'developers') return { status: 503, key: 'app.developers_only', message };
+  // restricted
+  if (!who.username) return { status: 403, key: 'app.restricted', message: null, signIn: true };
+  const user = who.username.toLowerCase();
+  return (app.availability_users ?? []).some((u) => u.toLowerCase() === user) ? null : { status: 403, key: 'app.restricted', message: null };
+}

package/src/runtime/context.ts

@@ -1,9 +1,9 @@
 import type { Download } from './processes.ts';
 import type { PassThrough } from 'node:stream';
 import type { PageCss } from '../css.ts';
-import type pg from 'pg';
+import pg from 'pg';
 import type { BindValues } from '../binds.ts';
-import type { Client } from '../db.ts';
+import { runtime, type Client } from '../db.ts';
 import type { Raw } from '../html.ts';
 import type { App, Button, Page } from '../metadata.ts';
 import type { Locale } from './locale.ts';
@@ -72,6 +72,16 @@ export interface PageContext {
   background?: boolean;
   /** debug messages of this request, when the app's debug level is on (src/debug.ts) */
   debug?: DebugLog;
+  /** (085) values of an Ajax callback's x01 … x10 parameters, as binds X01 … X10 */
+  extraBinds?: Record<string, string | null>;
+  /** (079) the developer whose builder session is open in this browser (the developer toolbar), if any */
+  devbar?: import('./devbar.ts').Devbar | null;
+  /** (078) the origins the response may frame (the request's set; security.ts adds them to the CSP) */
+  frameSrc?: Set<string> | null;
+  /** (086) the https origins of images the response shows (display image items; security.ts adds them to the CSP) */
+  imgSrc?: Set<string> | null;
+  /** (076) per form region: the checksum of its row when it was fetched (lost update detection) */
+  rowVersions?: Map<number, string>;
 }
 
 /** Write a debug message when this request records them (no-op otherwise). */
@@ -89,6 +99,8 @@ export function timed<T>(ctx: { debug?: DebugLog }, level: number, component: st
 export function bindValues(ctx: PageContext): BindValues {
   return {
     ...ctx.session.state,
+    // (085) :X01 … :X10 of an Ajax callback (never the built-in names below)
+    ...ctx.extraBinds,
     APP_USER: ctx.user,
     APP_ID: String(ctx.app.id),
     APP_ALIAS: ctx.app.alias,
@@ -152,11 +164,13 @@ export async function publicError(ctx: Pick<PageContext, 'app' | 'page' | 'user'
   const t = ctx.locale?.t ?? english;
   const err = e as pg.DatabaseError;
   dbg(ctx, 1, 'error', () => `${where}: ${err.code ? `[${err.code}] ` : ''}${err.message}${err.where ? ` (${err.where.split('\n')[0]})` : ''}`);
-  if (!err.code) return err.message;
-  if (err.code === 'P0001') return err.message;
+  const handled = (message: string, internal: boolean, reference: string | null = null) =>
+    errorFunction(ctx, { message, original_message: err.message ?? String(e), code: err.code ?? null, constraint: err.constraint ?? null, table: err.table ?? null,
+      column: err.column ?? null, detail: err.detail ?? null, hint: err.hint ?? null, component: where, page: ctx.page?.page_no ?? null, user: ctx.user, internal, reference });
+  if (!err.code || err.code === 'P0001') return handled(err.message, false);
   const friendly = FRIENDLY[err.code]?.(err, t);
   if (ctx.app.debug) return `${where}: ${err.message}`;
-  if (friendly) return friendly;
+  if (friendly) return handled(friendly, false);
   const ref = await logActivity({
     appId: ctx.app.id,
     pageNo: ctx.page?.page_no,
@@ -165,7 +179,33 @@ export async function publicError(ctx: Pick<PageContext, 'app' | 'page' | 'user'
     ip: ctx.ip,
     detail: `${where}: [${err.code}] ${err.message}`,
   });
-  return ref ? t('error.reference', { ref }) : t('error.unexpected');
+  return handled(ref ? t('error.reference', { ref }) : t('error.unexpected'), true, ref ?? null);
+}
+
+const ERROR_FUNCTION = /^([A-Za-z_][A-Za-z0-9_$]{0,62})\.([A-Za-z_][A-Za-z0-9_$]{0,62})$/;
+
+/**
+ * (085) The application's error handling function (APEX: Error Handling Function):
+ * schema.function(jsonb) returns jsonb, called as the application's role in a
+ * transaction of its own (2 s), with the message pgkiln would show and what it
+ * knows of the error. When it returns {"message": "…"}, that is shown instead;
+ * when it returns null or fails, the message stays.
+ */
+async function errorFunction(ctx: Pick<PageContext, 'app' | 'user'> & { debug?: DebugLog }, info: { message: string } & Record<string, unknown>) {
+  const fn = ERROR_FUNCTION.exec(ctx.app.error_function ?? '');
+  if (!fn) return info.message;
+  try {
+    const r = await runtime.tx(async (c) => {
+      await c.query(`set local statement_timeout = '2s'`);
+      await c.query(`select set_config('pgkiln.app_id', $1, true), set_config('pgkiln.app_user', $2, true)`, [String(ctx.app.id), ctx.user]);
+      if (ctx.app.db_role) await c.query(`set local role ${pg.escapeIdentifier(ctx.app.db_role)}`);
+      return (await c.query(`select ${pg.escapeIdentifier(fn[1])}.${pg.escapeIdentifier(fn[2])}($1::jsonb) as r`, [JSON.stringify(info)])).rows[0]?.r;
+    });
+    if (r && typeof r === 'object' && typeof r.message === 'string' && r.message.trim()) return r.message.trim().slice(0, 2000);
+  } catch (e) {
+    dbg(ctx, 1, 'error', () => `error handling function ${ctx.app.error_function}: ${(e as Error).message}`);
+  }
+  return info.message;
 }
 
 /** Write to a streamed response, waiting while the client is slow; fails once the client is gone. */

package/src/runtime/data-export.ts

@@ -0,0 +1,94 @@
+// The download process's {"export": "<format>"} (migration 086, APEX:
+// APEX_DATA_EXPORT): the process's query returns rows, and the file is
+// those rows as CSV, JSON, XML or HTML (meta.data_export, in SQL) or as
+// Excel or PDF (made here, as the report downloads make them).
+import { applyBinds } from '../binds.ts';
+import { savepoint } from '../db.ts';
+import type { Process } from '../metadata.ts';
+import { writeXlsx, XLSX_TYPE, type XlsxCell } from '../xlsx.ts';
+import { bindValues, stripSemicolon, substitute, type PageContext } from './context.ts';
+import { heading } from './items.ts';
+import { layoutFor, printable, tablePdf } from './pdf.ts';
+import { cell, isNumeric, xlsxCell } from './report.ts';
+import { safeFileName, type Download } from './processes.ts';
+
+export const EXPORT_FORMATS = ['csv', 'json', 'xml', 'html', 'xlsx', 'pdf'] as const;
+export type ExportFormat = (typeof EXPORT_FORMATS)[number];
+const TYPES: Record<ExportFormat, string> = {
+  csv: 'text/csv; charset=utf-8',
+  json: 'application/json',
+  xml: 'application/xml',
+  html: 'text/html; charset=utf-8',
+  xlsx: XLSX_TYPE,
+  pdf: 'application/pdf',
+};
+/** Excel and PDF hold at most this many rows (the rest is left out, with a note in the PDF). */
+export const EXPORT_MAX_ROWS = 100_000;
+
+export interface ExportConfig {
+  export?: ExportFormat;
+  /** the file's name without extension (&ITEM. substitutions); default: the process name */
+  file_name?: string;
+  /** the title of an HTML or PDF file (&ITEM. substitutions) */
+  title?: string;
+  /** a report layout for the PDF (Shared Components → Report layouts) */
+  layout?: string;
+  /** CSV: the separator (one character) */
+  separator?: string;
+}
+
+export function exportProblems(c: ExportConfig): string[] {
+  const out: string[] = [];
+  if (c.export !== undefined && !EXPORT_FORMATS.includes(c.export)) out.push(`"export" is one of ${EXPORT_FORMATS.join(', ')}.`);
+  for (const k of ['file_name', 'title', 'layout'] as const) if (c[k] !== undefined && typeof c[k] !== 'string') out.push(`"${k}" is text.`);
+  if (c.separator !== undefined && !(typeof c.separator === 'string' && /^[^"\r\n]$/.test(c.separator))) out.push('"separator" is one character.');
+  return out;
+}
+
+/** The process's rows as a file in the configured format. */
+export async function exportDownload(ctx: PageContext, p: Process, conf: ExportConfig): Promise<Download> {
+  const format = conf.export!;
+  const sql = stripSemicolon(applyBinds(p.code ?? '', bindValues(ctx)));
+  if (!sql) throw new Error(`Process "${p.name}" needs a query in its code.`);
+  const text = (s: string | undefined) => (s ? substitute(s, ctx, (v) => v) : '');
+  const name = `${safeFileName(text(conf.file_name) || p.name.toLowerCase(), 'export')}.${format}`;
+  const title = text(conf.title) || p.name;
+  const c = ctx.client!;
+  if (format !== 'xlsx' && format !== 'pdf') {
+    const opts = { title: format === 'html' ? title : undefined, separator: conf.separator };
+    const r = await savepoint(c, () => c.query<{ f: Buffer }>('select meta.data_export($1, $2, $3) as f', [sql, format, JSON.stringify(opts)]));
+    return { content: r.rows[0].f, name, type: TYPES[format], inline: false };
+  }
+  const res = await savepoint(c, () => c.query({ text: `select * from (\n${sql}\n) "__x" limit ${EXPORT_MAX_ROWS + 1}`, rowMode: 'array' }));
+  const fields = res.fields;
+  const rows = res.rows as unknown[][];
+  const truncated = rows.length > EXPORT_MAX_ROWS;
+  if (truncated) rows.length = EXPORT_MAX_ROWS;
+  const headings = fields.map((f) => ctx.locale.tr(heading(f.name)));
+  if (format === 'xlsx') {
+    const cells: XlsxCell[][] = rows.map((r) => r.map((v, i) => xlsxCell(v, fields[i].dataTypeID)));
+    return { content: writeXlsx({ name: title, headings, rows: cells }), name, type: TYPES.xlsx, inline: false };
+  }
+  const t = ctx.locale.t;
+  const layout = await layoutFor(ctx.app.id, conf.layout);
+  const now = new Date().toISOString();
+  const content = await tablePdf(
+    {
+      title: printable(title),
+      header: printable(`${ctx.app.name} · ${now.slice(0, 16).replace('T', ' ')} UTC · ${ctx.user}`),
+      footer: printable(title),
+      filters: [],
+      note: null,
+      endNote: () => (truncated ? printable(t('pdf.truncated', { rows: String(EXPORT_MAX_ROWS) })) : null),
+      headings: headings.map(printable),
+      rows: rows.map((r) => r.map((v, i) => printable(typeof v === 'boolean' ? (v ? t('item.yes') : t('item.no')) : cell(v, fields[i].dataTypeID)))),
+      align: fields.map((f) => (isNumeric(f.dataTypeID) ? 'right' : 'left')),
+      widths: fields.map(() => null),
+      noData: t('report.no_data'),
+      pageLabel: (page, pages) => t('pdf.page', { page: String(page), pages: String(pages) }),
+      info: { Title: printable(title), Author: ctx.user },
+    },
+    layout,
+  );
+  return { content, name, type: TYPES.pdf, inline: false };
+}

package/src/runtime/data-items.ts

@@ -0,0 +1,194 @@
+// Items of migration 086: display image (APEX: Display Image), geocoded
+// address (APEX: Geocoded Address) and items kept per user across sessions
+// (APEX: Maintain session state: Per User, stored in meta.user_preference).
+//
+// image   shows the item's value as a picture: an https URL, a path of this
+//         server, or a data:image URL. With {"sql": "select photo, photo_mime
+//         from hr.emp where id = :P3_ID"} the picture is the first column of
+//         the query's first row instead (a BLOB), served by
+//         GET /a/<alias>/<page>/image/<item> as the application's role.
+// address a text item with a "Check address" button: the installation's
+//         geocoder (GEOCODER_URL, src/geocode.ts) offers matching addresses;
+//         the one chosen replaces the text and its position goes into
+//         {"coordinates_item": "P3_LOCATION"} as "lat,lng".
+import { createHash } from 'node:crypto';
+import type { FastifyInstance, FastifyReply } from 'fastify';
+import { applyBinds, bindNames } from '../binds.ts';
+import { appTx, savepoint } from '../db.ts';
+import { geocode, geocoderUrl } from '../geocode.ts';
+import { html, raw, type Raw } from '../html.ts';
+import { icon } from '../icons.ts';
+import type { Item } from '../metadata.ts';
+import { checkPageAccess, computeVisibility, Forbidden } from './authz.ts';
+import { bindValues, dbg, publicError, stripSemicolon, substitute, toState, type PageContext } from './context.ts';
+
+type Loader = (req: any, reply: FastifyReply, opts?: { json?: boolean }) => Promise<PageContext | null>;
+type Tx = (ctx: PageContext) => Parameters<typeof appTx>[0];
+
+/** Picture types an image item serves (an SVG only sandboxed, as everything here). */
+const IMAGE_TYPES = new Set(['image/png', 'image/jpeg', 'image/gif', 'image/webp', 'image/avif', 'image/bmp', 'image/svg+xml']);
+export const IMAGE_MAX_BYTES = 20 * 1024 * 1024;
+const DATA_IMAGE = /^data:image\/(png|jpeg|gif|webp|avif);base64,[A-Za-z0-9+/=\s]+$/;
+
+/** A pixel size from the item's config (1–2000), or null. */
+const px = (v: unknown) => {
+  const n = Math.round(Number(v));
+  return Number.isFinite(n) && n >= 1 && n <= 2000 ? n : null;
+};
+
+/** Where an image item's picture comes from: a URL the page may show, or null. */
+export function imageUrl(ctx: PageContext, item: Item, value: string): string | null {
+  if (typeof item.config?.sql === 'string' && item.config.sql.trim()) {
+    // the query's binds: a new value gives a new URL (the picture is never cached)
+    const used = bindNames(item.config.sql).map((n) => `${n}=${ctx.session.state[n] ?? ''}`).join('&');
+    const v = createHash('sha256').update(used).digest('base64url').slice(0, 12);
+    return `${ctx.base}/${ctx.page.page_no}/image/${item.name}?v=${v}`;
+  }
+  const s = value.trim();
+  if (!s) return null;
+  if (DATA_IMAGE.test(s)) return s;
+  if (/^\/(?![/\\])/.test(s)) return s;
+  try {
+    const u = new URL(s);
+    if (u.protocol !== 'https:' || u.username || u.password) return null;
+    // the page's Content-Security-Policy allows this picture's origin (and no other)
+    ctx.imgSrc?.add(u.origin);
+    return u.href;
+  } catch {
+    return null;
+  }
+}
+
+/** The picture of an image item, or a blank display value. */
+export function imageControl(ctx: PageContext, item: Item, value: string): Raw {
+  const src = imageUrl(ctx, item, value);
+  if (!src) return html`<div class="display-value" id="${item.name}"> </div>`;
+  const alt = typeof item.config?.alt === 'string' ? substitute(item.config.alt, ctx, (v) => v) : (item.label ?? '');
+  const w = px(item.config?.width);
+  const h = px(item.config?.height);
+  return html`<div class="display-image" id="${item.name}"><img src="${src}" alt="${alt}"${w ? raw(` width="${w}"`) : ''}${h ? raw(` height="${h}"`) : ''} loading="lazy" decoding="async"></div>`;
+}
+
+/** A text input with a "Check address" button (when the installation has a geocoder). */
+export function addressControl(ctx: PageContext, item: Item, value: string, aria: Raw): Raw {
+  const id = item.name;
+  const input = html`<input type="text" id="${id}" name="${id}" value="${value}" autocomplete="street-address"${aria}>`;
+  if (!geocoderUrl()) return input;
+  const coords = typeof item.config?.coordinates_item === 'string' && /^[A-Z][A-Z0-9_]*$/.test(item.config.coordinates_item) ? item.config.coordinates_item : '';
+  return html`<div class="input-with-button">${input}
+      <button type="button" class="btn" data-geocode="${id}" data-url="${ctx.base}/${ctx.page.page_no}/geocode/${id}"${coords ? html` data-coords="${coords}"` : ''} aria-controls="${id}_places">${icon('map')} ${ctx.locale.t('item.check_address')}</button></div>
+    <ul class="geocode-places" id="${id}_places" role="listbox" aria-label="${ctx.locale.t('item.address_places')}" hidden></ul>`;
+}
+
+// ---------------------------------------------------------------- per-user items
+
+/** Items kept per user across sessions ({"persist": "user"}). */
+const persisted = (ctx: PageContext) =>
+  ctx.app.authentication === 'none' || !ctx.session.username ? [] : ctx.page.items.filter((i) => i.config?.persist === 'user');
+
+/** Before the page renders: the user's values of persisted items not set in this session. */
+export async function loadPreferences(ctx: PageContext) {
+  const names = persisted(ctx).map((i) => i.name).filter((n) => ctx.session.state[n] === undefined);
+  if (!names.length) return;
+  const c = ctx.client!;
+  const r = await savepoint(c, () => c.query<{ n: string; v: string | null }>('select n, meta.get_preference(n) as v from unnest($1::text[]) n', [names]));
+  for (const { n, v } of r.rows) if (v !== null) ctx.session.state[n] = v;
+  dbg(ctx, 6, 'session', `per-user items read: ${names.join(', ')}`);
+}
+
+/** After a submit: the user's values of the persisted items the page could change. */
+export async function savePreferences(ctx: PageContext) {
+  const items = persisted(ctx).filter((i) => ctx.vis?.editable.has(i.name));
+  if (!items.length) return;
+  const c = ctx.client!;
+  await c.query('select meta.set_preference(n, v) from unnest($1::text[], $2::text[]) as x(n, v)', [
+    items.map((i) => i.name),
+    items.map((i) => toState(ctx.session.state[i.name])),
+  ]);
+}
+
+// ---------------------------------------------------------------- routes
+
+/** One geocoder request per session and second at most. */
+const lastGeocode = new Map<string, number>();
+
+export function dataItemRoutes(app: FastifyInstance, loadContext: Loader, txContext: Tx) {
+  app.get('/a/:alias/:page/image/:item', async (req: any, reply) => {
+    const ctx = await loadContext(req, reply);
+    if (!ctx) return;
+    const name = String(req.params.item ?? '').toUpperCase();
+    try {
+      const file = await appTx(txContext(ctx), async (c) => {
+        ctx.client = c;
+        await checkPageAccess(ctx);
+        await computeVisibility(ctx);
+        const item = ctx.page.items.find((i) => i.name === name && i.type === 'image');
+        if (!item || !ctx.vis!.items.has(name) || typeof item.config?.sql !== 'string') return null;
+        const sql = stripSemicolon(applyBinds(item.config.sql, bindValues(ctx)));
+        const r = await savepoint(c, () => c.query({ text: `select * from (\n${sql}\n) "__i" limit 1`, rowMode: 'array' }));
+        const [content, mime] = (r.rows[0] ?? []) as [unknown, unknown];
+        if (!Buffer.isBuffer(content) || !content.length) return null;
+        return { content, mime: String(mime ?? '').toLowerCase().split(';')[0].trim() };
+      });
+      if (!file) return reply.code(404).header('cache-control', 'no-store').type('text/plain').send('');
+      if (file.content.length > IMAGE_MAX_BYTES) return reply.code(413).type('text/plain').send('');
+      const type = IMAGE_TYPES.has(file.mime) ? file.mime : sniff(file.content);
+      if (!type) return reply.code(415).type('text/plain').send('');
+      return reply
+        .header('content-security-policy', "default-src 'none'; style-src 'unsafe-inline'; sandbox")
+        .header('cache-control', 'private, no-store')
+        .type(type)
+        .send(file.content);
+    } catch (e) {
+      if (e instanceof Forbidden) return reply.code(403).type('text/plain').send('');
+      req.log.warn({ err: e }, 'image item');
+      await publicError(ctx, e, `image of ${name}`);
+      return reply.code(500).type('text/plain').send('');
+    }
+  });
+
+  app.post('/a/:alias/:page/geocode/:item', async (req: any, reply) => {
+    const ctx = await loadContext(req, reply, { json: true });
+    if (!ctx) return;
+    const body = (req.body ?? {}) as Record<string, unknown>;
+    if (body.__csrf !== ctx.session.csrf_token) return reply.code(403).send({ error: ctx.locale.t('error.session_reload') });
+    const name = String(req.params.item ?? '').toUpperCase();
+    const q = typeof body.q === 'string' ? body.q.trim().slice(0, 300) : '';
+    if (!geocoderUrl()) return reply.code(404).send({ error: ctx.locale.t('item.address_error') });
+    let item: Item | undefined;
+    try {
+      await appTx(txContext(ctx), async (c) => {
+        ctx.client = c;
+        await checkPageAccess(ctx);
+        await computeVisibility(ctx);
+        item = ctx.page.items.find((i) => i.name === name && i.type === 'address');
+        if (!item || !ctx.vis!.editable.has(name)) throw new Forbidden(ctx.locale.t('error.action_unavailable'));
+      });
+    } catch (e) {
+      if (e instanceof Forbidden) return reply.code(403).send({ error: e.message });
+      throw e;
+    }
+    if (q.length < 3) return reply.send({ places: [] });
+    const now = Date.now();
+    if (now - (lastGeocode.get(ctx.session.id) ?? 0) < 1000) return reply.code(429).send({ error: ctx.locale.t('item.address_error') });
+    lastGeocode.set(ctx.session.id, now);
+    if (lastGeocode.size > 10_000) for (const [k, t] of lastGeocode) if (now - t > 60_000) lastGeocode.delete(k);
+    try {
+      const country = typeof item!.config?.country === 'string' ? item!.config.country : null;
+      const places = await geocode(q, { language: ctx.locale.lang, country });
+      return reply.header('cache-control', 'no-store').send({ places });
+    } catch (e) {
+      req.log.warn({ err: e }, 'geocoder');
+      return reply.code(502).send({ error: ctx.locale.t('item.address_error') });
+    }
+  });
+}
+
+/** The picture type from the first bytes, when the query gave none. */
+function sniff(b: Buffer): string | null {
+  if (b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47) return 'image/png';
+  if (b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff) return 'image/jpeg';
+  if (b.subarray(0, 4).toString('latin1') === 'GIF8') return 'image/gif';
+  if (b.subarray(0, 4).toString('latin1') === 'RIFF' && b.subarray(8, 12).toString('latin1') === 'WEBP') return 'image/webp';
+  return null;
+}

package/src/runtime/devbar.ts

@@ -0,0 +1,182 @@
+// Developer toolbar (APEX: Runtime Developer Toolbar) and session state
+// viewer (APEX: Session → View session state), migration 079.
+//
+// A builder session hands the browser a second random token in the cookie
+// pgkiln_devbar (path /a, HttpOnly, SameSite=Lax); the database keeps its
+// sha256 on the builder session (meta.session.devbar_hash). A page of an
+// application shows the toolbar when that token belongs to a live builder
+// session of a developer who may open the application (an administrator, or
+// a member of its workspace). The token does nothing else: it is not the
+// builder session's token, and every builder request still needs that one.
+//
+// The toolbar links to the App Builder, the application and the page in the
+// Page Designer, shows the session state (GET /a/:alias/:page/devbar/session),
+// clears the page's items, and switches debug messages on for this session
+// only (POST …/devbar/debug; meta.session.state.__DEBUG_LEVEL, read by
+// loadContext).
+import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
+import { owner, runtime } from '../db.ts';
+import { DEBUG_LEVELS } from '../debug.ts';
+import { html, raw, type Raw } from '../html.ts';
+import { hashToken, newToken } from '../security.ts';
+import { saveState, sessionLimits, type Session } from '../session.ts';
+import { documentShell } from '../layout.ts';
+import type { PageContext } from './context.ts';
+
+export const DEVBAR_COOKIE = 'pgkiln_devbar';
+const COOKIE_PATH = '/a';
+const BUILDER = '/builder';
+/** The session state key of the session's own debug level. */
+export const SESSION_DEBUG = '__DEBUG_LEVEL';
+
+export interface Devbar {
+  username: string;
+}
+
+/** Builder: give the browser a toolbar token for this developer session (when it has none that matches). */
+export async function ensureDevbar(req: FastifyRequest, reply: FastifyReply, s: Session) {
+  if (!s.username) return;
+  const token = req.cookies[DEVBAR_COOKIE];
+  if (token && token.length <= 100 && s.devbar_hash && hashToken(token) === s.devbar_hash) return;
+  const fresh = newToken();
+  s.devbar_hash = hashToken(fresh);
+  await runtime.query('update meta.session set devbar_hash = $2 where id = $1 and app_id is null', [s.id, s.devbar_hash]);
+  reply.setCookie(DEVBAR_COOKIE, fresh, { path: COOKIE_PATH, httpOnly: true, sameSite: 'lax', secure: process.env.COOKIE_SECURE === 'true' });
+}
+
+/** Builder sign-out: the toolbar goes with the session. */
+export function clearDevbar(reply: FastifyReply) {
+  reply.clearCookie(DEVBAR_COOKIE, { path: COOKIE_PATH });
+}
+
+/** The developer whose live builder session the request's toolbar token belongs to, if they may open this application. */
+export async function devbarOf(req: FastifyRequest, appId: number): Promise<Devbar | null> {
+  const token = req.cookies?.[DEVBAR_COOKIE];
+  if (!token || token.length > 100) return null;
+  const { idleMinutes, maxHours } = sessionLimits();
+  const row = await owner.one<{ username: string }>(
+    `select s.username from meta.session s
+      where s.devbar_hash = $1 and s.app_id is null and s.username is not null
+        and s.last_seen > now() - make_interval(mins => $2) and s.created_at > now() - make_interval(hours => $3)
+        and exists (select 1 from meta.developer d where d.username = s.username
+                     and (d.is_admin or exists (select 1 from meta.workspace_member m
+                                                 where m.username = d.username and m.workspace_id = meta.app_workspace($4))))`,
+    [hashToken(token), idleMinutes, maxHours, appId],
+  );
+  return row ? { username: row.username } : null;
+}
+
+/** The session's own debug level (0: none), set from the toolbar. */
+export const sessionDebugLevel = (s: Session) => {
+  const n = Number(s.state[SESSION_DEBUG] ?? 0);
+  return DEBUG_LEVELS.some(([level]) => level === n) ? n : 0;
+};
+
+/** The toolbar at the bottom of a page (not in dialogs). */
+export function devbarHtml(ctx: PageContext): Raw | '' {
+  if (!ctx.devbar || ctx.dialog) return '';
+  const level = sessionDebugLevel(ctx.session);
+  const appLevel = Number(ctx.app.debug_level ?? 0);
+  const page = ctx.page.page_no;
+  return html`<details class="devbar" open>
+    <summary><span>Developer</span></summary>
+    <nav aria-label="Developer toolbar"><ul>
+      <li><a href="${BUILDER}">App Builder</a></li>
+      <li><a href="${BUILDER}/apps/${ctx.app.id}">Application ${ctx.app.id}</a></li>
+      <li><a href="${BUILDER}/pages/${ctx.page.id}">Edit page ${page}</a></li>
+      <li><a href="${ctx.base}/${page}/devbar/session">Session</a></li>
+      <li><form method="post" action="${ctx.base}/${page}/devbar/debug" class="devbar-debug">
+        <input type="hidden" name="__csrf" value="${ctx.session.csrf_token}">
+        <label for="devbar-debug">Debug</label>
+        <select id="devbar-debug" name="level">${DEBUG_LEVELS.map(([n, label]) =>
+          html`<option value="${n}"${n === level ? raw(' selected') : ''}>${n === 0 ? (appLevel ? `Application (${appLevel})` : 'Off') : label}</option>`)}</select>
+        <button>Set</button>
+      </form></li>
+      ${level || appLevel ? html`<li><a href="${BUILDER}/apps/${ctx.app.id}/debug">View debug</a></li>` : ''}
+    </ul></nav>
+  </details>`;
+}
+
+const INTERNAL = /^__/;
+
+/** Session state viewer and the toolbar's actions. */
+export function devbarRoutes(app: FastifyInstance, loadContext: (req: any, reply: FastifyReply) => Promise<PageContext | null>) {
+  const developerContext = async (req: FastifyRequest, reply: FastifyReply) => {
+    const ctx = await loadContext(req, reply);
+    if (!ctx) return null;
+    if (!ctx.devbar) {
+      reply.code(404).type('text/plain').send('Not found');
+      return null;
+    }
+    return ctx;
+  };
+
+  app.get('/a/:alias/:page/devbar/session', async (req, reply) => {
+    const ctx = await developerContext(req, reply);
+    if (!ctx) return;
+    const state = ctx.session.state;
+    const show = (name: string, type?: string) => {
+      const v = state[name];
+      if (v === undefined || v === null) return html`<span class="muted">(null)</span>`;
+      if (type === 'password') return html`<span class="muted">(set, not shown)</span>`;
+      return html`<code>${v.length > 2000 ? `${v.slice(0, 2000)}…` : v}</code>`;
+    };
+    const pageItems = ctx.page.items.map((i) => i.name);
+    const known = new Set([...pageItems, ...ctx.app.app_items]);
+    const others = Object.keys(state).filter((k) => !INTERNAL.test(k) && !known.has(k)).sort();
+    const table = (rows: Raw[], cols: string[]) =>
+      rows.length
+        ? html`<div class="table-wrap"><table class="report"><thead><tr>${cols.map((c) => html`<th scope="col">${c}</th>`)}</tr></thead><tbody>${rows}</tbody></table></div>`
+        : html`<p class="muted">None.</p>`;
+    const body = html`<main class="t-main devbar-session" id="main">
+      <div class="t-titlebar"><h1>Session state</h1></div>
+      <div class="t-content">
+        <p><a href="${ctx.base}/${ctx.page.page_no}">Back to page ${ctx.page.page_no}</a></p>
+        <dl class="devbar-facts">
+          <dt>Application</dt><dd>${ctx.app.name} (${ctx.app.alias}, ${ctx.app.id})</dd>
+          <dt>User</dt><dd>${ctx.user}</dd>
+          <dt>Roles</dt><dd>${ctx.roles.join(', ') || '–'}</dd>
+          <dt>Session</dt><dd><code>${ctx.session.id}</code></dd>
+          <dt>Language</dt><dd>${ctx.locale.lang}</dd>
+          <dt>Time zone</dt><dd>${ctx.locale.timeZone ?? '–'}</dd>
+          <dt>Debug</dt><dd>${sessionDebugLevel(ctx.session) ? `level ${sessionDebugLevel(ctx.session)} for this session` : Number(ctx.app.debug_level) ? `level ${ctx.app.debug_level} (application)` : 'off'}</dd>
+        </dl>
+        <h2>Page ${ctx.page.page_no}: ${ctx.page.name}</h2>
+        ${table(ctx.page.items.map((i) => html`<tr><td><code>${i.name}</code></td><td>${i.type}</td><td>${show(i.name, i.type)}</td></tr>`), ['Item', 'Type', 'Value'])}
+        <form method="post" action="${ctx.base}/${ctx.page.page_no}/devbar/clear">
+          <input type="hidden" name="__csrf" value="${ctx.session.csrf_token}">
+          <button class="btn">Clear the items of page ${ctx.page.page_no}</button>
+        </form>
+        <h2>Application items</h2>
+        ${table(ctx.app.app_items.map((n) => html`<tr><td><code>${n}</code></td><td>${show(n)}</td></tr>`), ['Item', 'Value'])}
+        <h2>Other values (items of other pages)</h2>
+        ${table(others.map((n) => html`<tr><td><code>${n}</code></td><td>${show(n)}</td></tr>`), ['Name', 'Value'])}
+      </div>
+    </main>`;
+    return reply.type('text/html').send(
+      documentShell(`Session state · ${ctx.app.name}`, body, 't-app devbar-page', { 'data-base': ctx.base }, '', {
+        lang: 'en', dir: 'ltr', theme: ctx.locale.theme, style: ctx.locale.style,
+      }),
+    );
+  });
+
+  app.post('/a/:alias/:page/devbar/clear', async (req: any, reply) => {
+    const ctx = await developerContext(req, reply);
+    if (!ctx) return;
+    if (req.body?.__csrf !== ctx.session.csrf_token) return reply.code(403).type('text/plain').send('Invalid CSRF token');
+    for (const i of ctx.page.items) delete ctx.session.state[i.name];
+    await saveState(ctx.session);
+    return reply.redirect(`${ctx.base}/${ctx.page.page_no}/devbar/session`, 303);
+  });
+
+  app.post('/a/:alias/:page/devbar/debug', async (req: any, reply) => {
+    const ctx = await developerContext(req, reply);
+    if (!ctx) return;
+    if (req.body?.__csrf !== ctx.session.csrf_token) return reply.code(403).type('text/plain').send('Invalid CSRF token');
+    const level = Number(req.body?.level);
+    if (level && DEBUG_LEVELS.some(([n]) => n === level)) ctx.session.state[SESSION_DEBUG] = String(level);
+    else delete ctx.session.state[SESSION_DEBUG];
+    await saveState(ctx.session);
+    return reply.redirect(`${ctx.base}/${ctx.page.page_no}`, 303);
+  });
+}