tina4-nodejs 3.13.147 → 3.13.149

package/packages/orm/src/adapters/mongodb.ts

@@ -64,11 +64,114 @@ function isMatchAllWhere(where: string | null | undefined): boolean {
   return where != null && MATCH_ALL_WHERE.test(where);
 }
 
+// ── Non-backtracking SQL scanning helpers (ReDoS-safe) ──────────────
+// The SQL dispatchers below parse with plain string operations (indexOf /
+// slice / single linear scan) instead of regexes with adjacent variable-length
+// groups (`\s+(.*?)\s+`), which CodeQL correctly flags as polynomial ReDoS.
+// This mirrors the Ruby master's string-based SQL parsing. Behaviour is
+// identical to the previous regexes on the ORM-generated SQL these see.
+
+const QUOTE_CHARS = "\"'";
+
+function isSqlWs(ch: string): boolean {
+  return ch === " " || ch === "\t" || ch === "\n" || ch === "\r" || ch === "\f" || ch === "\v";
+}
+
+function isWordChar(ch: string): boolean {
+  return (ch >= "a" && ch <= "z") || (ch >= "A" && ch <= "Z") || (ch >= "0" && ch <= "9") || ch === "_";
+}
+
+/** True when sql[start..end) is empty or all whitespace. */
+function onlyWs(sql: string, start: number, end: number): boolean {
+  for (let i = start; i < end; i++) if (!isSqlWs(sql[i])) return false;
+  return true;
+}
+
+/**
+ * Index of a whitespace-delimited keyword (matched case-insensitively against
+ * `upper`, the upper-cased sql) at or after `from`, or -1. Plain indexOf scan —
+ * no backtracking.
+ */
+function keywordAt(upper: string, keyword: string, from: number): number {
+  let at = upper.indexOf(keyword, from);
+  while (at >= 0) {
+    const end = at + keyword.length;
+    const okBefore = at === 0 || isSqlWs(upper[at - 1]);
+    const okAfter = end >= upper.length || isSqlWs(upper[end]);
+    if (okBefore && okAfter) return at;
+    at = upper.indexOf(keyword, at + 1);
+  }
+  return -1;
+}
+
+/** The lowest index among `positions` that is >= 0, else `fallback`. */
+function earliest(positions: number[], fallback: number): number {
+  let min = fallback;
+  for (const p of positions) if (p >= 0 && p < min) min = p;
+  return min;
+}
+
+/** Read an optionally-quoted identifier (a \w+ run) at/after `from`; [name, end] or null. */
+function readIdentifier(sql: string, from: number): [string, number] | null {
+  let i = from;
+  while (i < sql.length && isSqlWs(sql[i])) i++;
+  if (i < sql.length && QUOTE_CHARS.includes(sql[i])) i++;
+  const start = i;
+  while (i < sql.length && isWordChar(sql[i])) i++;
+  if (i === start) return null;
+  const name = sql.slice(start, i);
+  if (i < sql.length && QUOTE_CHARS.includes(sql[i])) i++;
+  return [name, i];
+}
+
+/**
+ * Index just past `keyword` (whitespace-delimited, case-insensitive) when it is
+ * the next token at/after `from` with only whitespace in between, else -1. Folds
+ * the recurring "find keyword + require all-whitespace gap" guard.
+ */
+function keywordGapEnd(upper: string, sql: string, keyword: string, from: number): number {
+  const at = keywordAt(upper, keyword, from);
+  if (at < 0 || !onlyWs(sql, from, at)) return -1;
+  return at + keyword.length;
+}
+
+/** Strip one leading and one trailing quote (matches /^["']|["']$/g). */
+function stripQuotes(value: string): string {
+  let result = value;
+  if (result.length > 0 && (result[0] === '"' || result[0] === "'")) result = result.slice(1);
+  const last = result.length - 1;
+  if (last >= 0 && (result[last] === '"' || result[last] === "'")) result = result.slice(0, last);
+  return result;
+}
+
+/**
+ * Split a WHERE clause on whitespace-delimited AND (case-insensitive), linearly.
+ * Each part is trimmed by the caller, so the surrounding whitespace that the old
+ * /\s+AND\s+/ delimiter consumed is dropped there too — identical result.
+ */
+function splitOnAnd(where: string): string[] {
+  const parts: string[] = [];
+  const lower = where.toLowerCase();
+  let segStart = 0;
+  let i = 0;
+  while (i < where.length) {
+    if (lower.startsWith("and", i) && i > 0 && isSqlWs(where[i - 1]) && i + 3 < where.length && isSqlWs(where[i + 3])) {
+      parts.push(where.slice(segStart, i));
+      i += 3;
+      segStart = i;
+      continue;
+    }
+    i++;
+  }
+  parts.push(where.slice(segStart));
+  return parts;
+}
+
 /** Convert SQL WHERE clause tokens into a MongoDB filter object. */
 function parseWhereClause(where: string, params: unknown[], paramOffset = 0): { filter: Record<string, unknown>; consumed: number } {
   const filter: Record<string, unknown> = {};
-  // Simple key = ? / key = 'value' patterns separated by AND
-  const parts = where.split(/\s+AND\s+/i);
+  // Simple key = ? / key = 'value' patterns separated by AND (linear split).
+  const parts = splitOnAnd(where);
   let paramIndex = paramOffset;
 
   for (const part of parts) {
@@ -191,27 +294,70 @@ function requireWriteFilter(filter: Record<string, unknown> | undefined, operati
   }
 }
 
-function parseSelect(sql: string, params: unknown[]): MongoOperation | null {
-  const match = sql.match(/^SELECT\s+(.*?)\s+FROM\s+["']?(\w+)["']?(?:\s+WHERE\s+(.*?))?(?:\s+ORDER\s+BY\s+(.*?))?(?:\s+LIMIT\s+(\d+))?(?:\s+OFFSET\s+(\d+))?$/is);
-  if (!match) return null;
-  const [, cols, collection, whereClause, orderBy, limitStr, skipStr] = match;
+/** Build a MongoDB projection document from a SELECT column list. */
+function buildProjection(cols: string): Record<string, unknown> {
   const projection: Record<string, unknown> = {};
-  if (cols && cols.trim() !== "*") {
-    for (const col of cols.split(",")) {
-      const name = col.trim().replace(/^["']|["']$/g, "");
-      if (name && name !== "*") projection[name] = 1;
-    }
+  if (!cols || cols.trim() === "*") return projection;
+  for (const col of cols.split(",")) {
+    const name = stripQuotes(col.trim());
+    if (name && name !== "*") projection[name] = 1;
   }
-  const filter = whereClause ? parseWhereClause(whereClause.trim(), params).filter : {};
+  return projection;
+}
+
+/** Remove a trailing whitespace-separated ASC/DESC (case-insensitive). */
+function stripTrailingDirection(part: string): string {
+  const lower = part.toLowerCase();
+  let suffix = 0;
+  if (lower.endsWith("asc")) suffix = 3;
+  else if (lower.endsWith("desc")) suffix = 4;
+  else return part;
+  const beforeIdx = part.length - suffix - 1;
+  if (beforeIdx < 0 || !isSqlWs(part[beforeIdx])) return part;
+  let i = beforeIdx;
+  while (i >= 0 && isSqlWs(part[i])) i--;
+  return part.slice(0, i + 1);
+}
+
+/** Build a MongoDB sort document from an ORDER BY clause. */
+function parseOrderBy(orderBy: string): Record<string, 1 | -1> {
   const sort: Record<string, 1 | -1> = {};
-  if (orderBy) {
-    for (const part of orderBy.split(",")) {
-      const trimmed = part.trim();
-      const desc = /DESC$/i.test(trimmed);
-      const col = trimmed.replace(/\s+(ASC|DESC)$/i, "").replace(/^["']|["']$/g, "").trim();
-      sort[col] = desc ? -1 : 1;
-    }
+  for (const rawPart of orderBy.split(",")) {
+    const trimmed = rawPart.trim();
+    const desc = trimmed.toLowerCase().endsWith("desc");
+    const col = stripQuotes(stripTrailingDirection(trimmed)).trim();
+    sort[col] = desc ? -1 : 1;
   }
+  return sort;
+}
+
+function parseSelect(sql: string, params: unknown[]): MongoOperation | null {
+  // Plain string scan — SELECT <cols> FROM <coll> [WHERE ..][ORDER BY ..][LIMIT n][OFFSET n].
+  const upper = sql.toUpperCase();
+  if (!(upper.startsWith("SELECT") && (sql.length === 6 || isSqlWs(sql[6])))) return null;
+  const fromAt = keywordAt(upper, "FROM", 6);
+  if (fromAt < 0) return null;
+  const cols = sql.slice(6, fromAt).trim();
+  const ident = readIdentifier(sql, fromAt + 4);
+  if (!ident) return null;
+  const [collection, afterColl] = ident;
+
+  const whereAt = keywordAt(upper, "WHERE", afterColl);
+  const orderAt = keywordAt(upper, "ORDER BY", afterColl);
+  const limitAt = keywordAt(upper, "LIMIT", afterColl);
+  const offsetAt = keywordAt(upper, "OFFSET", afterColl);
+  const end = sql.length;
+
+  const whereClause = whereAt < 0 ? undefined
+    : sql.slice(whereAt + 5, earliest([orderAt, limitAt, offsetAt], end)).trim();
+  const orderBy = orderAt < 0 ? undefined
+    : sql.slice(orderAt + 8, earliest([limitAt, offsetAt], end)).trim();
+  const limitStr = limitAt < 0 ? undefined
+    : sql.slice(limitAt + 5, earliest([offsetAt], end)).trim();
+  const skipStr = offsetAt < 0 ? undefined : sql.slice(offsetAt + 6).trim();
+
+  const projection = buildProjection(cols);
+  const filter = whereClause ? parseWhereClause(whereClause, params).filter : {};
   return {
     type: "find",
     collection,
@@ -219,7 +365,7 @@ function parseSelect(sql: string, params: unknown[]): MongoOperation | null {
     projection: Object.keys(projection).length > 0 ? projection : undefined,
     limit: limitStr ? parseInt(limitStr, 10) : undefined,
     skip: skipStr ? parseInt(skipStr, 10) : undefined,
-    sort: orderBy ? sort : undefined,
+    sort: orderBy ? parseOrderBy(orderBy) : undefined,
   };
 }
 
@@ -258,21 +404,36 @@ function parseSetClause(setClause: string, params: unknown[]): { document: Recor
 }
 
 function parseUpdate(sql: string, params: unknown[]): MongoOperation | null {
-  const match = sql.match(/^UPDATE\s+["']?(\w+)["']?\s+SET\s+(.*?)(?:\s+WHERE\s+(.+))?$/is);
-  if (!match) return null;
-  const [, collection, setClause, whereClause] = match;
+  // Plain string scan — UPDATE <coll> SET <assignments> [WHERE ..].
+  const upper = sql.toUpperCase();
+  if (!(upper.startsWith("UPDATE") && sql.length > 6 && isSqlWs(sql[6]))) return null;
+  const ident = readIdentifier(sql, 6);
+  if (!ident) return null;
+  const [collection, afterColl] = ident;
+  const setAt = keywordAt(upper, "SET", afterColl);
+  if (setAt < 0 || !onlyWs(sql, afterColl, setAt)) return null;
+  const whereAt = keywordAt(upper, "WHERE", setAt + 3);
+  const setClause = sql.slice(setAt + 3, whereAt < 0 ? sql.length : whereAt).trim();
+  const whereClause = whereAt < 0 ? undefined : sql.slice(whereAt + 5).trim();
   const set = parseSetClause(setClause, params);
-  const matchAll = isMatchAllWhere(whereClause?.trim());
-  const filter = whereClause ? parseWhereClause(whereClause.trim(), params, set.consumed).filter : {};
+  const matchAll = isMatchAllWhere(whereClause);
+  const filter = whereClause ? parseWhereClause(whereClause, params, set.consumed).filter : {};
   return { type: "updateMany", collection, filter, update: { $set: set.document }, matchAll };
 }
 
 function parseDelete(sql: string, params: unknown[]): MongoOperation | null {
-  const match = sql.match(/^DELETE\s+FROM\s+["']?(\w+)["']?(?:\s+WHERE\s+(.+))?$/is);
-  if (!match) return null;
-  const [, collection, whereClause] = match;
-  const matchAll = isMatchAllWhere(whereClause?.trim());
-  const filter = whereClause ? parseWhereClause(whereClause.trim(), params).filter : {};
+  // Plain string scan — DELETE FROM <coll> [WHERE ..].
+  const upper = sql.toUpperCase();
+  if (!upper.startsWith("DELETE")) return null;
+  const fromAt = keywordAt(upper, "FROM", 6);
+  if (fromAt < 0 || !onlyWs(sql, 6, fromAt)) return null;
+  const ident = readIdentifier(sql, fromAt + 4);
+  if (!ident) return null;
+  const [collection, afterColl] = ident;
+  const whereAt = keywordAt(upper, "WHERE", afterColl);
+  const whereClause = whereAt < 0 ? undefined : sql.slice(whereAt + 5).trim();
+  const matchAll = isMatchAllWhere(whereClause);
+  const filter = whereClause ? parseWhereClause(whereClause, params).filter : {};
   return { type: "deleteMany", collection, filter, matchAll };
 }
 
@@ -282,10 +443,24 @@ function parseCreate(sql: string): MongoOperation | null {
 }
 
 function parseCount(sql: string, params: unknown[]): MongoOperation | null {
-  const match = sql.match(/^SELECT\s+COUNT\(\*\)\s+AS\s+(\w+)\s+FROM\s+["']?(\w+)["']?(?:\s+WHERE\s+(.+))?$/is);
-  if (!match) return null;
-  const [, alias, collection, whereClause] = match;
-  const filter = whereClause ? parseWhereClause(whereClause.trim(), params).filter : {};
+  // Plain string scan — SELECT COUNT(*) AS <alias> FROM <coll> [WHERE ..].
+  const upper = sql.toUpperCase();
+  if (!upper.startsWith("SELECT")) return null;
+  const afterCount = keywordGapEnd(upper, sql, "COUNT(*)", 6);
+  if (afterCount < 0) return null;
+  const afterAs = keywordGapEnd(upper, sql, "AS", afterCount);
+  if (afterAs < 0) return null;
+  const aliasIdent = readIdentifier(sql, afterAs);
+  if (!aliasIdent) return null;
+  const [alias, afterAlias] = aliasIdent;
+  const afterFrom = keywordGapEnd(upper, sql, "FROM", afterAlias);
+  if (afterFrom < 0) return null;
+  const coll = readIdentifier(sql, afterFrom);
+  if (!coll) return null;
+  const [collection, afterColl] = coll;
+  const whereAt = keywordAt(upper, "WHERE", afterColl);
+  const whereClause = whereAt < 0 ? undefined : sql.slice(whereAt + 5).trim();
+  const filter = whereClause ? parseWhereClause(whereClause, params).filter : {};
   return { type: "aggregate", collection, pipeline: [{ $match: filter }, { $count: alias }] };
 }
 

package/packages/orm/src/autoCrud.ts

@@ -217,6 +217,15 @@ export function generateCrudRoutes(models: DiscoveredModel[], options: AutoCrudO
         let built: ReturnType<typeof buildQuery>;
         try {
           const qp = parseQueryString(req.query ?? {});
+          // ADR-0094: resolve the model's declared string/text columns for the
+          // ?search term (OR'd LIKE %term%). Resolved from the model, never the
+          // request, so only declared columns reach SQL (ADR-0069). A model with
+          // no string/text column yields an empty list and search matches nothing.
+          if ((qp.search ?? "").trim() !== "") {
+            qp.searchColumns = Object.entries(fields)
+              .filter(([, def]) => def.type === "string" || def.type === "text")
+              .map(([name]) => getDbCol(name));
+          }
           built = buildQuery(tableName, qp, extraConditions, q, (key) => resolveFieldColumn(fields, getDbCol, key));
         } catch (err) {
           if (err instanceof UnknownFieldError) {

package/packages/orm/src/crud.ts

@@ -0,0 +1,273 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
+/**
+ * Crud (ADR-0094) — a FRONTEND over AutoCrud.
+ *
+ * `Crud.toCrud(request, options)` renders a complete server-rendered admin UI
+ * (searchable, sortable, paginated table + create/edit/delete modals) for an ORM
+ * model. It owns NO backend routes: the entire REST backend (GET list, GET /{id},
+ * POST, PUT, DELETE, secure-by-default) is delegated to AutoCrud, and the UI's
+ * JavaScript talks to those routes over fetch(). The HTML comes from four
+ * app-overridable Frond templates under `crud/` (page, table, form, modals),
+ * resolved app-first-then-framework (the same convention the error pages use), so
+ * an app restyles the admin by dropping its own `src/templates/crud/<name>.twig`.
+ *
+ * Lives in @tina4/orm (next to AutoCrud, the ORM it drives) rather than in the
+ * eager @tina4/core barrel: Crud is an opt-in feature, not on every request
+ * path, so it must not be pulled into core's import graph (lazyFeatureLoading).
+ *
+ * Node returns `Promise<string>` (the DB adapters are async); the Python/PHP/Ruby
+ * entry points return a string. generateTable / generateForm stay synchronous.
+ *
+ * Usage:
+ *   get("/admin/users", async (request, response) =>
+ *     response.html(await Crud.toCrud(request, { model: User, title: "Users" }))
+ *   ).secure();
+ *
+ * A custom `sql` only shapes the LISTING grid (a filter/join/projection); the
+ * model still drives columns, the primary key, and every write path, so a custom
+ * listing can never create an unauthenticated or divergent write route.
+ */
+
+import type { Tina4Request } from "../../core/src/types.js";
+import { defaultRouter } from "../../core/src/router.js";
+import { generateCrudRoutes } from "./autoCrud.js";
+import { getAdapter, adapterQuery, adapterFetch } from "./database.js";
+import {
+  type CrudModel,
+  h,
+  columnOf,
+  primaryKeyProp,
+  searchableProps,
+  crudSortProp,
+  stripOrderAndLimit,
+  extractColumns,
+} from "./crudHelpers.js";
+import { jsConfig, pageControls, tableData } from "./crudTable.js";
+import { renderCrudTemplate, renderModals, generateTable, generateForm } from "./crudRender.js";
+
+export type { CrudModel } from "./crudHelpers.js";
+export type { FormFieldDef } from "./crudRender.js";
+export { generateTable, generateForm } from "./crudRender.js";
+export { stripOrderAndLimit } from "./crudHelpers.js";
+
+export interface ToCrudOptions {
+  /** REQUIRED — the ORM model class (a BaseModel subclass). */
+  model: CrudModel;
+  /** Optional listing query (inferred from the model when omitted); shapes only the displayed grid. */
+  sql?: string;
+  /** Page title (default "CRUD"). */
+  title?: string;
+  /** AutoCrud route prefix (default "/api"). */
+  prefix?: string;
+  /** Records per page (default 10). */
+  limit?: number;
+  /** When true, the AutoCrud write routes are OPEN (no auth). Default false (secure). */
+  public?: boolean;
+}
+
+/** (prefix, table) pairs whose AutoCrud routes have already been registered. */
+const registeredTables = new Set<string>();
+
+/** Reset the registration cache (tests). */
+export function _resetCrudRegistrations(): void {
+  registeredTables.clear();
+}
+
+/** Build the DiscoveredModel shape generateCrudRoutes expects from a model class. */
+function discoveredFrom(model: CrudModel): any {
+  return {
+    filePath: `src/models/${model.name ?? model.tableName}.ts`,
+    modelClass: model,
+    definition: {
+      tableName: model.tableName,
+      className: model.name,
+      fields: model.fields,
+      fieldMapping: model.fieldMapping,
+      softDelete: (model as any).softDelete ?? false,
+      tableFilter: (model as any).tableFilter,
+      dbName: (model as any)._db,
+    },
+  };
+}
+
+/**
+ * Delegate the ENTIRE backend to AutoCrud. Idempotent per (prefix, table):
+ * the first registration wins (so a scaffolded route that opted writes public
+ * is not later reset to secure), and addRoute replaces a route in place anyway.
+ */
+export async function registerBackend(
+  model: CrudModel,
+  options: { prefix?: string; public?: boolean } = {},
+): Promise<void> {
+  const prefix = options.prefix ?? "/api";
+  const key = `${prefix}::${model.tableName}`;
+  if (registeredTables.has(key)) return;
+
+  const routes = generateCrudRoutes([discoveredFrom(model)], { public: options.public === true });
+  for (const route of routes) defaultRouter.addRoute(route);
+  registeredTables.add(key);
+}
+
+interface FetchOpts { search: string; sort: string; sortDir: string; limit: number; offset: number; }
+
+/** Fetch a page of records from the model (ADR-0069 safe search + sort). */
+async function fetchModelData(model: CrudModel, opts: FetchOpts): Promise<[Array<Record<string, unknown>>, number]> {
+  const orderBy = `${opts.sort} ${opts.sortDir.toUpperCase()}`;
+  const search = opts.search.trim();
+  const searchable = search === "" ? [] : searchableProps(model);
+
+  let rows: any;
+  if (searchable.length === 0) {
+    rows = await model.all(opts.limit, opts.offset, undefined, orderBy);
+  } else {
+    const whereClause = searchable.map((prop) => `${columnOf(model, prop)} LIKE ?`).join(" OR ");
+    const params = searchable.map(() => `%${search}%`);
+    rows = await model.where(whereClause, params, opts.limit, opts.offset, undefined, orderBy);
+  }
+  const total = typeof rows.getTotalRecords === "function" ? rows.getTotalRecords() : rows.length;
+  const records = (rows as any[]).map((r) => (typeof r.toDict === "function" ? r.toDict() : r));
+  return [records, total];
+}
+
+/** Fetch a page of rows for a custom listing SQL (shapes the DISPLAY only). */
+async function fetchSqlData(sql: string, opts: FetchOpts): Promise<[Array<Record<string, unknown>>, number]> {
+  let adapter: any;
+  try {
+    adapter = getAdapter();
+  } catch {
+    return [[], 0];
+  }
+
+  const base = stripOrderAndLimit(sql);
+  const dir = opts.sortDir.toUpperCase();
+  const search = opts.search.trim();
+
+  if (search === "") {
+    const countRow = await adapterQuery(adapter, `SELECT COUNT(*) as cnt FROM (${base}) AS _crud_cnt`, []);
+    const total = Number(countRow[0]?.cnt ?? 0);
+    const rows = await adapterFetch(adapter, `${base} ORDER BY ${opts.sort} ${dir}`, [], opts.limit, opts.offset);
+    return [rows as Array<Record<string, unknown>>, total];
+  }
+
+  const columns = extractColumns(sql);
+  const searchParts = columns.map((col) => `CAST(${col} AS TEXT) LIKE ?`);
+  const params = columns.map(() => `%${search}%`);
+  const countRow = await adapterQuery(
+    adapter,
+    `SELECT COUNT(*) as cnt FROM (${base}) AS _crud_cnt WHERE ${searchParts.join(" OR ")}`,
+    params,
+  );
+  const total = Number(countRow[0]?.cnt ?? 0);
+  const rows = await adapterFetch(
+    adapter,
+    `SELECT * FROM (${base}) AS _crud_sub WHERE ${searchParts.join(" OR ")} ORDER BY ${opts.sort} ${dir}`,
+    params,
+    opts.limit,
+    opts.offset,
+  );
+  return [rows as Array<Record<string, unknown>>, total];
+}
+
+interface CrudRequest {
+  page: number; search: string; sortProp: string; sortColumn: string; sortDir: string;
+  offset: number; requestPath: string;
+}
+
+/** Parse pagination / search / safe-sort from the request query string. */
+function parseCrudRequest(request: Tina4Request, model: CrudModel, pkProp: string, limit: number): CrudRequest {
+  const query = (request && (request as any).query) || {};
+  const page = Math.max(parseInt(String(query.page ?? "1"), 10) || 1, 1);
+  const search = String(query.search ?? "").trim();
+  const sortProp = crudSortProp(model, query.sort, pkProp);   // header/state key (property)
+  const sortColumn = columnOf(model, sortProp);               // DB column for ORDER BY
+  const sortDir = query.sort_dir === "desc" ? "desc" : "asc";
+  const requestPath = (request && typeof (request as any).path === "string") ? (request as any).path : "/";
+  return { page, search, sortProp, sortColumn, sortDir, offset: (page - 1) * limit, requestPath };
+}
+
+/** Clamp the configured records-per-page to a positive integer (default 10). */
+function clampLimit(raw: number | undefined): number {
+  const limit = Number(raw ?? 10);
+  return !Number.isFinite(limit) || limit <= 0 ? 10 : limit;
+}
+
+/**
+ * Render the CRUD admin page for `model` and register its AutoCrud routes.
+ * Returns the rendered crud/page template.
+ */
+export async function toCrud(request: Tina4Request, options: ToCrudOptions): Promise<string> {
+  const model = options.model;
+  if (!model || !model.tableName || !model.fields) {
+    throw new Error("Crud.toCrud requires a model (an ORM class)");
+  }
+
+  const sql = options.sql;
+  const title = String(options.title ?? "CRUD");
+  const prefix = String(options.prefix ?? "/api");
+  const limit = clampLimit(options.limit);
+
+  const tableName = String(model.tableName);
+  const pkProp = primaryKeyProp(model);
+  const columns = Object.keys(model.fields);
+
+  // Backend: delegate 100% to AutoCrud (idempotent — register once).
+  await registerBackend(model, { prefix, public: options.public });
+
+  const req = parseCrudRequest(request, model, pkProp, limit);
+  const fetchOpts: FetchOpts = {
+    search: req.search, sort: req.sortColumn, sortDir: req.sortDir, limit, offset: req.offset,
+  };
+  const [records, total] = sql
+    ? await fetchSqlData(sql, fetchOpts)
+    : await fetchModelData(model, fetchOpts);
+
+  const totalPages = total > 0 ? Math.ceil(total / limit) : 1;
+  const apiPath = `${prefix}/${tableName}`;
+  const editableColumns = columns.filter((c) => c !== pkProp);
+
+  const tableHtml = renderCrudTemplate(
+    "table",
+    tableData({
+      columns, records, pk: pkProp, tableName, editable: false, sortable: true,
+      inlineScript: false, requestPath: req.requestPath, search: req.search, sortCol: req.sortProp,
+      sortDir: req.sortDir, page: req.page, limit, tableId: null, model,
+    }),
+  );
+
+  return renderCrudTemplate("page", {
+    title: h(title),
+    search: h(req.search),
+    request_path: h(req.requestPath),
+    info_count: records.length,
+    info_total: total,
+    info_page: req.page,
+    info_total_pages: totalPages,
+    table_html: tableHtml,
+    modals_html: renderModals(editableColumns, pkProp),
+    show_pagination: totalPages > 1,
+    controls: pageControls(req.page, totalPages, req.requestPath, req.search, req.sortProp, req.sortDir, limit),
+    config_json: jsConfig({
+      apiPath, pk: pkProp, columns, editable: editableColumns, model, limit,
+      search: req.search, sortCol: req.sortProp, sortDir: req.sortDir, page: req.page,
+    }),
+  });
+}
+
+/** The public Crud surface (ADR-0094). `CRUD` is an uppercase alias. */
+export const Crud = {
+  toCrud,
+  registerBackend,
+  generateTable,
+  generateForm,
+  stripOrderAndLimit,
+  _resetCrudRegistrations,
+};
+
+export const CRUD = Crud;