@cosmicdrift/kumiko-framework 0.388.0 → 0.390.0

package/dist/api/export/export-cells.js

@@ -0,0 +1,136 @@
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import { referenceCell } from "./export-cells-reference.js";
+const DATE_FORMAT = "yyyy-mm-dd";
+const TIMESTAMP_FORMAT = "yyyy-mm-dd hh:mm";
+const PLAIN_MONEY_FORMAT = "#,##0.00";
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+const CURRENCY_CODE = /^[A-Z]{3}$/;
+function isNullish(value) {
+    return value === null || value === undefined;
+}
+function textCell(value) {
+    return { value, type: String };
+}
+function numberCell(value, format) {
+    return { value, type: Number, ...(format !== undefined && { format }) };
+}
+function toFiniteNumber(value) {
+    const n = typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN;
+    return value !== "" && Number.isFinite(n) ? n : undefined;
+}
+function stringify(value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "object" && value !== null) {
+        // Temporal values stringify to ISO via toString; plain data goes through JSON.
+        const text = String(value);
+        return text === "[object Object]" ? JSON.stringify(value) : text;
+    }
+    return String(value);
+}
+function fromEpochMillis(value) {
+    if (value instanceof Date)
+        return Number.isNaN(value.getTime()) ? undefined : value;
+    if (typeof value === "object" && value !== null && "epochMilliseconds" in value) {
+        return fromEpochMillis(new Date(Number(value.epochMilliseconds)));
+    }
+    if (typeof value === "string" || typeof value === "number") {
+        return fromEpochMillis(new Date(value));
+    }
+    return undefined;
+}
+// Date-only values are anchored at UTC midnight, never parsed through the local zone.
+function toUtcDate(value) {
+    const text = typeof value === "string" ? value : isNullish(value) ? "" : stringify(value);
+    if (ISO_DATE.test(text))
+        return fromEpochMillis(new Date(`${text}T00:00:00Z`));
+    return undefined;
+}
+function dateCell(value) {
+    const date = toUtcDate(value) ?? fromEpochMillis(value);
+    return date === undefined
+        ? textCell(stringify(value))
+        : { value: date, type: Date, format: DATE_FORMAT };
+}
+// The sheet has no time zone, so the instant is shifted to the wall clock of `timeZone` and
+// stored as if that wall clock were UTC.
+function timestampCell(value, timeZone) {
+    const date = fromEpochMillis(value);
+    if (date === undefined)
+        return textCell(stringify(value));
+    const wall = Temporal.Instant.fromEpochMilliseconds(date.getTime()).toZonedDateTimeISO(timeZone);
+    const shifted = new Date(Date.UTC(wall.year, wall.month - 1, wall.day, wall.hour, wall.minute, wall.second));
+    return { value: shifted, type: Date, format: TIMESTAMP_FORMAT };
+}
+// `at` is the wall clock in the record's own zone without offset; reading it as UTC keeps the
+// digits the user saw in the list.
+function locatedTimestampCell(value) {
+    const at = typeof value === "object" && value !== null && "at" in value ? String(value.at) : undefined;
+    const date = at === undefined ? undefined : fromEpochMillis(new Date(`${at}Z`));
+    return date === undefined
+        ? textCell(stringify(value))
+        : { value: date, type: Date, format: TIMESTAMP_FORMAT };
+}
+function moneyCell(value) {
+    if (typeof value !== "object" || value === null || !("amount" in value)) {
+        const n = toFiniteNumber(value);
+        return n === undefined ? textCell(stringify(value)) : numberCell(n, PLAIN_MONEY_FORMAT);
+    }
+    const amount = toFiniteNumber(value.amount);
+    if (amount === undefined)
+        return textCell(stringify(value.amount));
+    const currency = "currency" in value ? String(value.currency) : "";
+    const format = CURRENCY_CODE.test(currency)
+        ? `${PLAIN_MONEY_FORMAT} "${currency}"`
+        : PLAIN_MONEY_FORMAT;
+    return numberCell(amount, format);
+}
+function integerCell(value, kind) {
+    const n = toFiniteNumber(value);
+    if (n === undefined)
+        return textCell(stringify(value));
+    // A bigInt beyond 2^53 would lose digits as a spreadsheet number.
+    if (kind === "bigInt" && !Number.isSafeInteger(n))
+        return textCell(stringify(value));
+    return numberCell(n);
+}
+function optionLabel(prefix, raw, translate) {
+    const text = String(raw);
+    const label = translate(`${prefix}${text}`);
+    return label === `${prefix}${text}` ? text : label;
+}
+function autoCell(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return numberCell(value);
+    if (typeof value === "boolean")
+        return { value, type: Boolean };
+    return textCell(stringify(value));
+}
+function optionCell(cell, value, translate) {
+    const values = cell.kind === "multiSelect" && Array.isArray(value) ? value : [value];
+    return textCell(values.map((v) => optionLabel(cell.optionLabelKeyPrefix, v, translate)).join(", "));
+}
+const SIMPLE_CELL_BUILDERS = {
+    number: (value) => integerCell(value, "number"),
+    decimal: (value) => integerCell(value, "decimal"),
+    bigInt: (value) => integerCell(value, "bigInt"),
+    money: (value) => moneyCell(value),
+    date: (value) => dateCell(value),
+    timestamp: timestampCell,
+    locatedTimestamp: (value) => locatedTimestampCell(value),
+    boolean: (value) => typeof value === "boolean" ? { value, type: Boolean } : textCell(stringify(value)),
+    auto: (value) => autoCell(value),
+    text: (value) => textCell(stringify(value)),
+};
+/** Never emits a formula cell and never reinterprets strings: text always stays text. */
+export function toExportCell(column, context) {
+    const { cell, field } = column;
+    const value = context.row[field];
+    if (isNullish(value))
+        return null;
+    if (cell.kind === "reference")
+        return referenceCell(cell, field, context.row);
+    if ("optionLabelKeyPrefix" in cell)
+        return optionCell(cell, value, context.translate);
+    return SIMPLE_CELL_BUILDERS[cell.kind](value, context.timeZone);
+}

package/dist/api/export/export-ciphertext-guard.d.ts

@@ -0,0 +1,2 @@
+import type { SheetData } from "write-excel-file/node";
+export declare function guardSheetAgainstCiphertext(sheet: SheetData, isProduction?: boolean): SheetData;

package/dist/api/export/export-ciphertext-guard.js

@@ -0,0 +1,27 @@
+import { InternalError } from "../../errors/index.js";
+import { createFallbackLogger } from "../../logging/utils.js";
+import { CIPHERTEXT_RE, CIPHERTEXT_REDACT_RE, CIPHERTEXT_REDACTION } from "../pii-leak-guard.js";
+const log = createFallbackLogger("kumiko:export-xlsx");
+// The response guard only scans JSON, so a workbook needs its own check: a ciphertext in a cell
+// means a raw DB read reached the export. Same policy as the guard: loud outside production,
+// redacted and logged in production.
+function guardText(text, isProduction) {
+    if (!CIPHERTEXT_RE.test(text))
+        return text;
+    const detail = "XLSX export contains a PII ciphertext — a raw DB read leaked into the sheet. " +
+        "Decrypt before returning (decryptStoredPii / executor read path).";
+    if (!isProduction)
+        throw new InternalError({ message: detail });
+    log.error(detail);
+    return text.replace(CIPHERTEXT_REDACT_RE, CIPHERTEXT_REDACTION);
+}
+function guardCell(cell, isProduction) {
+    if (typeof cell !== "object" || cell === null || !("value" in cell))
+        return cell;
+    if (typeof cell.value !== "string")
+        return cell;
+    return { ...cell, value: guardText(cell.value, isProduction) };
+}
+export function guardSheetAgainstCiphertext(sheet, isProduction = process.env["NODE_ENV"] === "production") {
+    return sheet.map((row) => row.map((cell) => guardCell(cell, isProduction)));
+}

package/dist/api/export/export-columns.d.ts

@@ -0,0 +1,31 @@
+import type { EntityDefinition } from "@cosmicdrift/kumiko-types/fields";
+import type { ListColumnSpec } from "@cosmicdrift/kumiko-types/screen";
+import type { SessionUser } from "../../engine/types/index.ts";
+import type { ReferenceCellKind } from "./export-cells-reference.ts";
+export type SimpleCellKind = "text" | "number" | "decimal" | "bigInt" | "money" | "date" | "timestamp" | "locatedTimestamp" | "boolean" | "auto";
+export type ExportCellKind = {
+    readonly kind: SimpleCellKind;
+} | ReferenceCellKind | {
+    readonly kind: "select" | "multiSelect";
+    /** `<feature>:entity:<entity>:field:<field>:option:` — the option value is appended. */
+    readonly optionLabelKeyPrefix: string;
+};
+export type ExportColumn = {
+    readonly field: string;
+    readonly headerKey: string;
+    readonly headerFallback: string;
+    readonly cell: ExportCellKind;
+};
+export type ExportColumnSource = {
+    readonly featureName: string;
+    readonly columns: readonly ListColumnSpec[];
+    readonly entity: EntityDefinition | undefined;
+    readonly entityName: string | undefined;
+    readonly user: Pick<SessionUser, "roles">;
+};
+/**
+ * Resolves the requested column ids against the screen's declared columns, in client order.
+ * Virtual columns and, on an entityList, encrypted/sensitive fields are dropped without error:
+ * the zip response bypasses the PII-leak guard, so this is the only place that keeps them out.
+ */
+export declare function resolveExportColumns(source: ExportColumnSource, requested: readonly string[]): ExportColumn[];

package/dist/api/export/export-columns.js

@@ -0,0 +1,85 @@
+import { holdsCiphertextOrSecret } from "../../db/entity-field-encryption.js";
+import { userMayReadFieldInBulk } from "../../engine/field-access.js";
+import { normalizeListColumn } from "../../engine/screen-helpers.js";
+import { exportRejection } from "./export-errors.js";
+const PROJECTION_PSEUDO_ENTITY = "__projection__";
+const FIELD_KIND_BY_TYPE = {
+    number: "number",
+    decimal: "decimal",
+    bigInt: "bigInt",
+    money: "money",
+    date: "date",
+    timestamp: "timestamp",
+    locatedTimestamp: "locatedTimestamp",
+    boolean: "boolean",
+};
+function fieldLabelKey(featureName, entityName, field) {
+    return `${featureName}:entity:${entityName}:field:${field}`;
+}
+function entityCellKind(source, entity, field) {
+    const def = entity.fields[field];
+    if (def?.type === "reference") {
+        return {
+            kind: "reference",
+            labelField: def.labelField ?? "id",
+            multiple: def.multiple === true,
+        };
+    }
+    const type = def?.type ?? "text";
+    if (type === "select" || type === "multiSelect") {
+        return {
+            kind: type,
+            optionLabelKeyPrefix: `${fieldLabelKey(source.featureName, source.entityName ?? "", field)}:option:`,
+        };
+    }
+    return { kind: FIELD_KIND_BY_TYPE[type] ?? "text" };
+}
+function projectionCellKind(valueType) {
+    if (valueType === "number" || valueType === "decimal" || valueType === "bigInt") {
+        return { kind: valueType };
+    }
+    return { kind: valueType === "money" ? "money" : "auto" };
+}
+function isExportableOnEntity(source, entity, field, virtual) {
+    if (virtual || !userMayReadFieldInBulk(entity, field, source.user))
+        return false;
+    return !holdsCiphertextOrSecret(entity, field);
+}
+/**
+ * Resolves the requested column ids against the screen's declared columns, in client order.
+ * Virtual columns and, on an entityList, encrypted/sensitive fields are dropped without error:
+ * the zip response bypasses the PII-leak guard, so this is the only place that keeps them out.
+ */
+export function resolveExportColumns(source, requested) {
+    const declared = new Map(source.columns.map((spec) => normalizeListColumn(spec)).map((c) => [c.field, c]));
+    const seen = new Set();
+    const resolved = [];
+    for (const field of requested) {
+        const column = declared.get(field);
+        if (column === undefined) {
+            throw exportRejection("export_unknown_column", "columns", { column: field });
+        }
+        if (seen.has(field))
+            continue;
+        seen.add(field);
+        const virtual = column.virtual === true;
+        const { entity } = source;
+        if (entity !== undefined && !isExportableOnEntity(source, entity, field, virtual))
+            continue;
+        if (entity === undefined && virtual)
+            continue;
+        const cell = entity !== undefined
+            ? entityCellKind(source, entity, field)
+            : projectionCellKind(column.valueType);
+        const headerEntity = source.entityName ?? PROJECTION_PSEUDO_ENTITY;
+        resolved.push({
+            field,
+            headerKey: column.label ?? fieldLabelKey(source.featureName, headerEntity, field),
+            headerFallback: column.label ?? field,
+            cell,
+        });
+    }
+    if (resolved.length === 0)
+        throw exportRejection("export_no_columns", "columns");
+    return resolved;
+}

package/dist/api/export/export-errors.d.ts

@@ -0,0 +1,4 @@
+import { ValidationError } from "../../errors/index.ts";
+export declare const EXPORT_TOO_MANY_I18N_KEY = "kumiko.list.export-too-many";
+export type ExportRejectReason = "export_invalid_request" | "export_unknown_screen" | "export_not_enabled" | "export_unknown_column" | "export_no_columns";
+export declare function exportRejection(reason: ExportRejectReason, path: string, params?: Readonly<Record<string, unknown>>): ValidationError;

package/dist/api/export/export-errors.js

@@ -0,0 +1,14 @@
+import { ValidationError } from "../../errors/index.js";
+export const EXPORT_TOO_MANY_I18N_KEY = "kumiko.list.export-too-many";
+export function exportRejection(reason, path, params) {
+    return new ValidationError({
+        fields: [
+            {
+                path,
+                code: reason,
+                i18nKey: `kumiko.list.${reason.replace(/_/g, "-")}`,
+                ...(params !== undefined && { params }),
+            },
+        ],
+    });
+}

package/dist/api/export/export-route.d.ts

@@ -0,0 +1,4 @@
+import { Hono } from "hono";
+import type { Registry } from "../../engine/types/index.ts";
+import type { Dispatcher } from "../../pipeline/dispatcher.ts";
+export declare function createExportRoutes(dispatcher: Dispatcher, registry: Registry): Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;

package/dist/api/export/export-route.js

@@ -0,0 +1,75 @@
+import { Hono } from "hono";
+import * as z from "zod";
+import { toKumikoError } from "../../errors/to-kumiko-error.js";
+import { createI18n } from "../../i18n/index.js";
+import { DEFAULT_LOCALE } from "../../i18n/request-locale.js";
+import { isValidIanaTimeZone } from "../../time/index.js";
+import { Routes } from "../api-constants.js";
+import { getUser } from "../auth-middleware.js";
+import { requestContext } from "../request-context.js";
+import { assertPayloadDepthAllowed, queryErrorResponse } from "../routes.js";
+import { EXPORT_TOO_MANY_I18N_KEY, exportRejection } from "./export-errors.js";
+import { readExportRows } from "./export-rows.js";
+import { resolveExportPlan } from "./export-screen.js";
+import { writeExportWorkbook } from "./export-xlsx-writer.js";
+const XLSX_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+const MAX_ID_LENGTH = 200;
+const exportBodySchema = z.object({
+    screen: z.string().max(MAX_ID_LENGTH),
+    payload: z.record(z.string(), z.unknown()).default({}),
+    columns: z.array(z.string().max(MAX_ID_LENGTH)).min(1).max(MAX_ID_LENGTH),
+    timeZone: z.string().max(64).optional(),
+});
+// Browser zone first (what the user saw in the list), then the profile zone, else UTC.
+function exportTimeZone(requested, profile) {
+    for (const candidate of [requested, profile]) {
+        if (candidate !== undefined && isValidIanaTimeZone(candidate))
+            return candidate;
+    }
+    return "UTC";
+}
+function downloadFileName(screenShortId, now) {
+    const safeId = screenShortId.replace(/[^A-Za-z0-9_-]/g, "_");
+    return `${safeId}-${now.toISOString().slice(0, 10)}.xlsx`;
+}
+export function createExportRoutes(dispatcher, registry) {
+    const api = new Hono();
+    const i18n = createI18n(registry, { defaultLocale: DEFAULT_LOCALE });
+    api.post(Routes.exportXlsx, async (c) => {
+        const user = getUser(c);
+        try {
+            const parsed = exportBodySchema.safeParse(await c.req.json().catch(() => undefined));
+            if (!parsed.success)
+                throw exportRejection("export_invalid_request", "body");
+            const body = parsed.data;
+            assertPayloadDepthAllowed(body.payload);
+            const plan = resolveExportPlan(registry, body.screen, body.columns, user);
+            const result = await readExportRows(dispatcher, plan, body.payload, user);
+            if (result.tooMany) {
+                return c.json({
+                    error: {
+                        code: "export_too_many_rows",
+                        httpStatus: 413,
+                        message: `export exceeds the limit of ${plan.maxRows} rows; narrow the filter`,
+                        i18nKey: EXPORT_TOO_MANY_I18N_KEY,
+                        details: { maxRows: plan.maxRows },
+                    },
+                }, 413);
+            }
+            const locale = requestContext.get()?.locale ?? DEFAULT_LOCALE;
+            const bytes = await writeExportWorkbook(plan.columns, result.rows, (key) => i18n.t(key, locale), exportTimeZone(body.timeZone, user.timezone));
+            return new Response(bytes, {
+                status: 200,
+                headers: {
+                    "Content-Type": XLSX_CONTENT_TYPE,
+                    "Cache-Control": "no-store",
+                    "Content-Disposition": `attachment; filename="${downloadFileName(plan.screenShortId, new Date())}"`,
+                },
+            });
+        }
+        catch (e) {
+            return queryErrorResponse(c, toKumikoError(e), Routes.exportXlsx);
+        }
+    });
+    return api;
+}

package/dist/api/export/export-rows.d.ts

@@ -0,0 +1,13 @@
+import type { SessionUser } from "../../engine/types/index.ts";
+import type { Dispatcher } from "../../pipeline/dispatcher.ts";
+import type { ExportPlan } from "./export-screen.ts";
+export type ExportRow = Readonly<Record<string, unknown>>;
+export type ExportRowsResult = {
+    readonly tooMany: false;
+    readonly rows: readonly ExportRow[];
+} | {
+    readonly tooMany: true;
+};
+export declare function sanitizeExportPayload(clientPayload: Readonly<Record<string, unknown>>, plan: Pick<ExportPlan, "screenFilter">): Record<string, unknown>;
+/** Reads the whole filtered list page by page; gives up as soon as more than `maxRows` exist. */
+export declare function readExportRows(dispatcher: Pick<Dispatcher, "query">, plan: ExportPlan, clientPayload: Readonly<Record<string, unknown>>, user: SessionUser): Promise<ExportRowsResult>;

package/dist/api/export/export-rows.js

@@ -0,0 +1,62 @@
+import { MAX_LIST_LIMIT } from "../../engine/entity-handlers.js";
+import { InternalError } from "../../errors/index.js";
+import { isPlainObject } from "../../utils/is-plain-object.js";
+// Paging, sizing and aggregation belong to the server here; `filter` is replaced from the screen
+// below, so a client can neither widen the fixed screen filter nor smuggle another one in.
+const CLIENT_CONTROLLED_PAGING_KEYS = [
+    "limit",
+    "offset",
+    "cursor",
+    "totalCount",
+    "aggregate",
+    "includeDeleted",
+    "filter",
+];
+export function sanitizeExportPayload(clientPayload, plan) {
+    const payload = { ...clientPayload };
+    for (const key of CLIENT_CONTROLLED_PAGING_KEYS)
+        delete payload[key];
+    if (plan.screenFilter !== undefined)
+        payload["filter"] = plan.screenFilter;
+    return payload;
+}
+function parsePage(result, queryType) {
+    if (!isPlainObject(result) || !Array.isArray(result["rows"])) {
+        throw new InternalError({
+            message: `export: query ${queryType} did not return a { rows } envelope`,
+        });
+    }
+    const nextCursor = result["nextCursor"];
+    return {
+        rows: result["rows"].filter(isPlainObject),
+        nextCursor: typeof nextCursor === "string" && nextCursor !== "" ? nextCursor : undefined,
+    };
+}
+/** Reads the whole filtered list page by page; gives up as soon as more than `maxRows` exist. */
+export async function readExportRows(dispatcher, plan, clientPayload, user) {
+    const base = sanitizeExportPayload(clientPayload, plan);
+    const rows = [];
+    const seenCursors = new Set();
+    let cursor;
+    for (;;) {
+        const limit = Math.min(MAX_LIST_LIMIT, plan.maxRows + 1 - rows.length);
+        const pagingPayload = cursor !== undefined
+            ? { ...base, limit, cursor }
+            : rows.length > 0
+                ? { ...base, limit, offset: rows.length }
+                : { ...base, limit };
+        const page = parsePage(await dispatcher.query(plan.queryType, pagingPayload, user), plan.queryType);
+        rows.push(...page.rows);
+        if (rows.length > plan.maxRows)
+            return { tooMany: true };
+        // A short or empty page is the end of the list; a repeated cursor would loop forever.
+        if (page.rows.length < limit || page.rows.length === 0)
+            return { tooMany: false, rows };
+        if (page.nextCursor !== undefined) {
+            if (seenCursors.has(page.nextCursor))
+                return { tooMany: false, rows };
+            seenCursors.add(page.nextCursor);
+        }
+        cursor = page.nextCursor;
+    }
+}

package/dist/api/export/export-screen.d.ts

@@ -0,0 +1,13 @@
+import type { ScreenFilter } from "@cosmicdrift/kumiko-types/screen";
+import type { Registry, SessionUser } from "../../engine/types/index.ts";
+import { type ExportColumn } from "./export-columns.ts";
+export type ExportPlan = {
+    readonly screenShortId: string;
+    readonly queryType: string;
+    readonly screenFilter: ScreenFilter | undefined;
+    readonly columns: readonly ExportColumn[];
+    readonly maxRows: number;
+};
+type ExportScreenRegistry = Pick<Registry, "getScreen" | "getScreenFeature" | "getEntity">;
+export declare function resolveExportPlan(registry: ExportScreenRegistry, screenQn: string, requestedColumns: readonly string[], user: Pick<SessionUser, "roles">): ExportPlan;
+export {};

package/dist/api/export/export-screen.js

@@ -0,0 +1,47 @@
+import { hasAccess } from "../../engine/access.js";
+import { toKebab } from "../../engine/qualified-name.js";
+import { DEFAULT_EXPORT_MAX_ROWS } from "../../engine/types/screen.js";
+import { AccessDeniedError } from "../../errors/index.js";
+import { resolveExportColumns } from "./export-columns.js";
+import { exportRejection } from "./export-errors.js";
+const SCREEN_QN = /^[A-Za-z0-9_-]+:screen:[A-Za-z0-9_-]+$/;
+function findExportScreen(registry, screenQn) {
+    // The client sends the feature name as authored (camelCase allowed); the registry keys are kebab.
+    const registryQn = toKebab(screenQn);
+    const screen = SCREEN_QN.test(screenQn) ? registry.getScreen(registryQn) : undefined;
+    if (screen === undefined || (screen.type !== "entityList" && screen.type !== "projectionList")) {
+        throw exportRejection("export_unknown_screen", "screen");
+    }
+    return { registryQn, screen };
+}
+export function resolveExportPlan(registry, screenQn, requestedColumns, user) {
+    const { registryQn, screen } = findExportScreen(registry, screenQn);
+    if (screen.table?.export?.xlsx !== true)
+        throw exportRejection("export_not_enabled", "screen");
+    if (screen.access !== undefined && !hasAccess(user, screen.access)) {
+        throw new AccessDeniedError({ details: { screen: screenQn } });
+    }
+    // Label keys use the feature name as authored, query types the kebab form.
+    const featureName = registry.getScreenFeature(registryQn) ?? "";
+    const screenShortId = registryQn.split(":")[2] ?? "";
+    const maxRows = screen.table.export.maxRows ?? DEFAULT_EXPORT_MAX_ROWS;
+    if (screen.type === "projectionList") {
+        return {
+            screenShortId,
+            queryType: screen.query,
+            screenFilter: screen.filter,
+            columns: resolveExportColumns({ featureName, columns: screen.columns, entity: undefined, entityName: undefined, user }, requestedColumns),
+            maxRows,
+        };
+    }
+    const entity = registry.getEntity(screen.entity);
+    if (entity === undefined)
+        throw exportRejection("export_unknown_screen", "screen");
+    return {
+        screenShortId,
+        queryType: `${toKebab(featureName)}:query:${toKebab(screen.entity)}:list`,
+        screenFilter: screen.filter,
+        columns: resolveExportColumns({ featureName, columns: screen.columns, entity, entityName: screen.entity, user }, requestedColumns),
+        maxRows,
+    };
+}

package/dist/api/export/export-xlsx-writer.d.ts

@@ -0,0 +1,4 @@
+import { type Translate } from "./export-cells.ts";
+import type { ExportColumn } from "./export-columns.ts";
+import type { ExportRow } from "./export-rows.ts";
+export declare function writeExportWorkbook(columns: readonly ExportColumn[], rows: readonly ExportRow[], translate: Translate, timeZone: string): Promise<Uint8Array<ArrayBuffer>>;

package/dist/api/export/export-xlsx-writer.js

@@ -0,0 +1,21 @@
+import writeXlsxFile, {} from "write-excel-file/node";
+import { toExportCell } from "./export-cells.js";
+import { guardSheetAgainstCiphertext } from "./export-ciphertext-guard.js";
+function headerLabel(column, translate) {
+    const translated = translate(column.headerKey);
+    return translated === column.headerKey ? column.headerFallback : translated;
+}
+export async function writeExportWorkbook(columns, rows, translate, timeZone) {
+    const header = columns.map((column) => ({
+        value: headerLabel(column, translate),
+        type: String,
+        fontWeight: "bold",
+    }));
+    const body = rows.map((row) => columns.map((column) => toExportCell(column, { row, translate, timeZone })));
+    const sheetData = guardSheetAgainstCiphertext([header, ...body]);
+    const buffer = await writeXlsxFile(sheetData, {}).toBuffer();
+    // Buffer is typed over ArrayBufferLike; a plain copy gives Response a BodyInit-compatible view.
+    const bytes = new Uint8Array(buffer.byteLength);
+    bytes.set(buffer);
+    return bytes;
+}

package/dist/api/extra-route.d.ts

@@ -1,5 +1,7 @@
+import type { WriteResult } from "@cosmicdrift/kumiko-types/handlers";
+import type { HttpRouteMethod } from "@cosmicdrift/kumiko-types/http-route";
 import type { Context, Hono } from "hono";
-import type { HttpRouteMethod, Registry, SessionUser, TenantId, WriteResult } from "../engine/types/index.ts";
+import type { Registry, SessionUser, TenantId } from "../engine/types/index.ts";
 import type { SecretsContext } from "../secrets/index.ts";
 export declare const ExtraRouteEntries: {
     readonly anonymous: "anonymous";
@@ -70,6 +72,10 @@ export type SignatureExtraRouteDeps = {
      *  caller's authenticity (signature, HMAC state, etc.). */
     readonly dispatchSystemWrite: (args: SystemDispatchArgs) => Promise<WriteResult>;
     readonly dispatchSystemQuery: (args: SystemDispatchArgs) => Promise<unknown>;
+    /** Same trust as dispatchSystemWrite, but runs as the tenant's system user
+     *  with the "system" role plus exactly `roles` (no SystemAdmin), so the write
+     *  passes app-role access checks. */
+    readonly dispatchWriteAs: (args: RoleDispatchArgs) => Promise<WriteResult>;
 };
 export type SignatureExtraRoute<TVerified> = {
     readonly method: HttpRouteMethod;

package/dist/api/index.d.ts

@@ -1,40 +1,36 @@
 export { DEFAULT_GLOBAL_RATE_LIMIT } from "../rate-limit/middleware.ts";
-export type { SetTenantCookieOptions } from "./anonymous-cookie.ts";
-export { deleteTenantCookie, setTenantCookie } from "./anonymous-cookie.ts";
+export { setTenantCookie } from "./anonymous-cookie.ts";
 export { collectAnonymousLiveEntities } from "./anonymous-live-entities.ts";
 export { LOCALE_HEADER_NAME, NO_ROUTE_MATCH_HEADER_NAME } from "./api-constants.ts";
-export type { AnonymousAccessConfig, AnonymousAccessResolved, AuthMiddlewareOptions, AuthSessionChecker, AuthSessionCheckResult, AuthSessionStatus, TenantExists, TenantLifecycleStatusResolver, TenantResolver, TokenVerifier, } from "./auth-middleware.ts";
-export { authMiddleware, CSRF_HEADER_NAME, getUser, PAT_TOKEN_PREFIX, sessionCheckStatus, } from "./auth-middleware.ts";
+export type { AnonymousAccessConfig, AnonymousAccessResolved, AuthSessionCheckResult, TokenVerifier, } from "./auth-middleware.ts";
+export { CSRF_HEADER_NAME, PAT_TOKEN_PREFIX, } from "./auth-middleware.ts";
 export type { AuthRoutesConfig, LoginRateLimiter, SessionChecker, SessionCreator, SessionMassRevoker, SessionMetadata, SessionRevoker, } from "./auth-routes.ts";
-export { createAuthRoutes, createInMemoryLoginRateLimiter, createRedisLoginRateLimiter, } from "./auth-routes.ts";
-export type { ClientIpHeaderSource, ClientIpResolver } from "./client-ip.ts";
-export { assertValidTrustedProxyHops, clientIpSourceFromHonoContext, createClientIpResolver, extractSocketAddress, parseTrustedProxyHopsEnv, TRUSTED_PROXY_HOPS_ENV, UNKNOWN_CLIENT_IP, } from "./client-ip.ts";
-export type { AnonymousExtraRoute, AnonymousExtraRouteDeps, ExtraRouteDefinition, ExtraRouteEntry, ExtraRouteRejectionOptions, ExtraRouteRejectionStatus, RoleDispatchArgs, SignatureExtraRoute, SignatureExtraRouteDeps, SignatureExtraRouteVerifyDeps, SignatureExtraRouteVerifyRequest, SystemDispatchArgs, UserExtraRoute, UserExtraRouteDeps, } from "./extra-route.ts";
-export { ExtraRouteEntries, ExtraRouteRejection, signatureRoute } from "./extra-route.ts";
-export type { CachedResponseInit, CachePolicy } from "./http-cache.ts";
-export { cacheControlHeader, cachedResponse, computeRevisionEtag, computeStrongEtag, computeWeakEtag, etagMatches, parseIfNoneMatch, } from "./http-cache.ts";
-export type { JwtHelper, JwtKeyring, JwtPayload } from "./jwt.ts";
-export { createJwtHelper, loadJwtSecretOrKeyring } from "./jwt.ts";
+export { createInMemoryLoginRateLimiter, createRedisLoginRateLimiter, } from "./auth-routes.ts";
+export type { ClientIpResolver } from "./client-ip.ts";
+export { createClientIpResolver, parseTrustedProxyHopsEnv, TRUSTED_PROXY_HOPS_ENV, UNKNOWN_CLIENT_IP, } from "./client-ip.ts";
+export type { AnonymousExtraRoute, AnonymousExtraRouteDeps, ExtraRouteDefinition, RoleDispatchArgs, SignatureExtraRouteDeps, SignatureExtraRouteVerifyRequest, SystemDispatchArgs, UserExtraRouteDeps, } from "./extra-route.ts";
+export { ExtraRouteRejection, signatureRoute } from "./extra-route.ts";
+export type { CachePolicy } from "./http-cache.ts";
+export { cacheControlHeader, cachedResponse, computeRevisionEtag, computeStrongEtag, computeWeakEtag, etagMatches, } from "./http-cache.ts";
+export type { JwtHelper } from "./jwt.ts";
+export { loadJwtSecretOrKeyring } from "./jwt.ts";
 export { publicOriginOf } from "./origin-middleware.ts";
-export { patAllows, qnMatches } from "./pat-scope.ts";
-export type { PostAuthLandingArgs, PostAuthLandingFlow, PostAuthLandingResolver, } from "./post-auth-landing.ts";
-export { isSafeLandingPath } from "./post-auth-landing.ts";
-export type { RedisSseBroker, RedisSseBrokerOptions } from "./redis-sse-broker.ts";
+export type { PostAuthLandingArgs, PostAuthLandingResolver, } from "./post-auth-landing.ts";
+export type { RedisSseBroker } from "./redis-sse-broker.ts";
 export { createDefaultSseBroker, createRedisSseBroker, isRedisSseBroker, } from "./redis-sse-broker.ts";
-export { type RequestContextData, readonlyRequestContext as requestContext, } from "./request-context.ts";
-export { buildRequestContextDataFromRequest, requestIdMiddleware, } from "./request-id-middleware.ts";
+export { readonlyRequestContext as requestContext } from "./request-context-scopes.ts";
+export { buildRequestContextDataFromRequest } from "./request-id-middleware.ts";
 export type { MetricsRouteOptions } from "./route-registrars.ts";
 export { createMetricsApp, DEFAULT_MAX_REQUEST_BYTES, isPrometheusMeter, } from "./route-registrars.ts";
-export { createApiRoutes } from "./routes.ts";
-export type { KumikoServer, ServerOptions } from "./server.ts";
+export type { ServerOptions } from "./server.ts";
 export { buildServer } from "./server.ts";
+export { resolveBaseDbAndSearchAdapter } from "./server-event-dispatcher.ts";
 export { makeDispatchSystemQuery, makeDispatchSystemWrite, makeDispatchWriteAs, } from "./server-extra-routes.ts";
 export { withFileProviderResolver } from "./server-wiring.ts";
-export type { ResolvedSessionCookies, SessionCookieBase, SessionCookieNames, } from "./session-cookies.ts";
-export { AUTH_COOKIE_BASE, CSRF_COOKIE_BASE, getSessionCookies, HOST_COOKIE_PREFIX, isHostPrefixedCookieName, resolveSessionCookieNames, resolveSessionCookies, sessionCookieName, sessionCookiesMiddleware, TENANT_COOKIE_BASE, } from "./session-cookies.ts";
-export type { SseBroker, SseClient, SseEvent } from "./sse-broker.ts";
+export { AUTH_COOKIE_BASE, CSRF_COOKIE_BASE, getSessionCookies, sessionCookieName, } from "./session-cookies.ts";
+export type { SseBroker, SseEvent } from "./sse-broker.ts";
 export { createSseBroker } from "./sse-broker.ts";
-export { createSseRoute, SSE_HEARTBEAT_INTERVAL_MS, type SseRouteOptions } from "./sse-route.ts";
+export { SSE_HEARTBEAT_INTERVAL_MS } from "./sse-route.ts";
 export { generateToken } from "./tokens.ts";
-export type { KumikoServeEnv, KumikoServerWebSocket, KumikoWebSocketData, WebSocketUpgradeServer, } from "./websocket-route.ts";
-export { createKumikoWebSocketHandler, isWebSocketUpgradeRequest, kumikoWebSocketHandler, WEBSOCKET_BACKPRESSURE_LIMIT_BYTES, WEBSOCKET_DEFAULT_MAX_CONNECTIONS_PER_USER, WEBSOCKET_HEARTBEAT_INTERVAL_MS, WEBSOCKET_MAX_PAYLOAD_BYTES, WEBSOCKET_PENDING_BUFFER_LIMIT_BYTES, WEBSOCKET_REVALIDATION_FAILURE_LIMIT, WEBSOCKET_ROUTE_PATH_PREFIX, } from "./websocket-route.ts";
+export type { KumikoServeEnv, KumikoWebSocketData, } from "./websocket-route.ts";
+export { createKumikoWebSocketHandler, isWebSocketUpgradeRequest, WEBSOCKET_BACKPRESSURE_LIMIT_BYTES, WEBSOCKET_HEARTBEAT_INTERVAL_MS, WEBSOCKET_MAX_PAYLOAD_BYTES, WEBSOCKET_PENDING_BUFFER_LIMIT_BYTES, WEBSOCKET_ROUTE_PATH_PREFIX, } from "./websocket-route.ts";