@cosmicdrift/kumiko-framework 0.386.0 → 0.388.0

package/dist/db/event-store-executor-read-sort.js

@@ -0,0 +1,130 @@
+import { buildOwnershipClause, normalizeAccessEntry, shiftParams, } from "../engine/ownership.js";
+import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
+import { isListSortAllowed, isSensitiveLabelField } from "./entity-field-encryption.js";
+import { isSoftDeletedTargetHidden } from "./event-store-executor-read-search.js";
+import { buildEntityTable, physicalColumnName } from "./table-builder.js";
+import { schemaTableName } from "./table-introspection.js";
+// Projected alongside the row when a reference sort is active, so the keyset
+// cursor carries the label that was ordered by instead of the FK's UUID.
+const SORT_LABEL_ALIAS = "__kumiko_sort_label";
+// Resolve a `sortable: true` reference field's label inline for
+// ORDER BY. A correlated scalar subquery, not a join: the result set keeps one
+// row per entity row, the read model stays untouched, and the lookup rides the
+// target's primary key. Tenant-scoped exactly like the search path — a foreign
+// tenant's label must never influence this tenant's ordering.
+// undefined means "cannot order by this label", which drops the sort to plain
+// id order; falling back to the UUID column would look deliberate to the user
+// while being arbitrary, which is worse than no sorting.
+function buildReferenceSortExpr(outerTableName, ownColumnSql, descriptor, resolveEntity, db, user) {
+    const targetEntity = resolveEntity(descriptor.targetEntityName);
+    if (targetEntity === undefined) {
+        // skip: unknown target entity — registry inconsistency the boot-validator
+        // should have caught; drop the sort rather than 500 the request
+        return undefined;
+    }
+    if (targetEntity.fields[descriptor.labelField] === undefined) {
+        // skip: labelField isn't a real (declared) column on the target entity
+        return undefined;
+    }
+    if (isSensitiveLabelField(targetEntity, descriptor.labelField)) {
+        // skip: encrypted/PII labelField — ciphertext orders by its bytes, which is
+        // arbitrary to the reader and would also rank rows by their stored secret
+        return undefined;
+    }
+    const targetTable = buildEntityTable(descriptor.targetEntityName, targetEntity);
+    // The order of labels the viewer may not read would leak them bit by bit, same as the search path.
+    const labelAccess = buildOwnershipClause(user, normalizeAccessEntry(targetEntity.fields[descriptor.labelField]?.access?.read), targetTable);
+    if (labelAccess.kind !== "pass")
+        return undefined;
+    const ownership = buildOwnershipClause(user, targetEntity.access?.read, targetTable);
+    if (ownership.kind === "empty")
+        return undefined;
+    const targetTableName = String(schemaTableName(targetTable));
+    const labelCol = physicalColumnName(targetTable, descriptor.labelField);
+    const tenantScoped = targetTable["tenantId"] !== undefined && db.mode === "tenant";
+    const tenantCol = tenantScoped ? physicalColumnName(targetTable, "tenantId") : "";
+    const tenantId = db.mode === "tenant" ? db.tenantId : undefined;
+    const deletedClause = isSoftDeletedTargetHidden(targetEntity, targetTable)
+        ? ` AND t."${physicalColumnName(targetTable, "isDeleted")}" = FALSE`
+        : "";
+    // No ::text cast (unlike the ILIKE search path): a non-text label must keep
+    // its native collation/numeric order, and the keyset param infers its type
+    // from the comparison anyway.
+    return (params) => {
+        let tenantClause = "";
+        if (tenantScoped) {
+            params.push(tenantId, SYSTEM_TENANT_ID);
+            tenantClause = ` AND t."${tenantCol}" IN ($${params.length - 1}, $${params.length})`;
+        }
+        let ownershipClause = "";
+        if (ownership.kind === "sql") {
+            const shifted = shiftParams({ sqlText: ownership.sqlText, params: ownership.params }, params.length);
+            for (const p of shifted.params)
+                params.push(p);
+            ownershipClause = ` AND ${shifted.sqlText}`;
+        }
+        return (`(SELECT t."${labelCol}" FROM "${targetTableName}" t ` +
+            `WHERE t."id" = "${outerTableName}".${ownColumnSql}${tenantClause}${ownershipClause}${deletedClause})`);
+    };
+}
+export function resolveListSort(request) {
+    const { payload, table, entity, referenceSort } = request;
+    // A column sort must not 400 (the renderer sends one per header click), and the order of
+    // ciphertext carries no meaning for the user while leaking the order of the plaintext.
+    const field = payload.sort &&
+        Object.hasOwn(table, payload.sort) &&
+        request.fieldReadClause(payload.sort).kind === "pass" &&
+        isListSortAllowed(entity, payload.sort)
+        ? payload.sort
+        : undefined;
+    if (field === undefined)
+        return { kind: "unsorted" };
+    const descending = payload.sortDirection === "desc";
+    if (entity.fields[field]?.type !== "reference")
+        return { kind: "column", field, descending };
+    // A reference column stores a UUID, so it is never sorted by
+    // directly: either the field opted into `sortable` and we order by the
+    // target row's label, or the sort is dropped to plain id order.
+    const descriptor = referenceSort?.fields.find((f) => f.fieldName === field);
+    const labelSql = referenceSort && descriptor
+        ? buildReferenceSortExpr(request.tableName, request.colSql(field), descriptor, referenceSort.resolveEntity, request.db, request.user)
+        : undefined;
+    return labelSql === undefined
+        ? { kind: "unsorted" }
+        : { kind: "referenceLabel", field, descending, labelSql };
+}
+export function renderSortSql(sort, where) {
+    return sort.kind === "referenceLabel" ? sort.labelSql(where.params) : where.colSql(sort.field);
+}
+export function renderListOrderBy(sort, where) {
+    const idAscending = `${where.colSql("id")} ASC`;
+    if (sort.kind === "unsorted") {
+        return { orderByClause: ` ORDER BY ${idAscending}`, sortLabelProjection: "" };
+    }
+    const sortSql = renderSortSql(sort, where);
+    const direction = sort.descending ? "DESC" : "ASC";
+    if (sort.kind === "column") {
+        return {
+            orderByClause: ` ORDER BY ${sortSql} ${direction}, ${idAscending}`,
+            sortLabelProjection: "",
+        };
+    }
+    // The projected label alias is ordered by directly, so Postgres evaluates
+    // the correlated subquery once per row instead of once for ORDER BY and
+    // once for the SELECT list. Projecting it also lets the keyset cursor carry
+    // the value that was ordered by rather than the FK column's UUID.
+    return {
+        orderByClause: ` ORDER BY "${SORT_LABEL_ALIAS}" ${direction}, ${idAscending}`,
+        sortLabelProjection: `, ${sortSql} AS "${SORT_LABEL_ALIAS}"`,
+    };
+}
+// The label alias is a query artifact, not a column of this entity, so it is
+// stripped before coercion; the last row's label feeds the keyset cursor.
+export function takeLastSortLabel(rawRows, sort) {
+    const lastSortLabel = rawRows[rawRows.length - 1]?.[SORT_LABEL_ALIAS];
+    if (sort.kind === "referenceLabel") {
+        for (const row of rawRows)
+            delete row[SORT_LABEL_ALIAS];
+    }
+    return lastSortLabel;
+}

package/dist/db/event-store-executor-read-where.d.ts

@@ -0,0 +1,24 @@
+import { type OwnershipClause } from "../engine/ownership.ts";
+import type { SessionUser } from "../engine/types/index.ts";
+import type { EventStoreExecutor } from "./event-store-executor.ts";
+import type { ExecutorContext } from "./event-store-executor-context.ts";
+import { type ListWhere } from "./event-store-executor-read-filter.ts";
+import { type ParentVisibilityOption } from "./parent-ref-clause.ts";
+import type { TenantDb } from "./tenant-db.ts";
+export type ListRuntimeOptions = NonNullable<Parameters<EventStoreExecutor["list"]>[3]>;
+export type ListWherePayload = Pick<Parameters<EventStoreExecutor["list"]>[0], "search" | "filter" | "filters">;
+export type FieldReadClause = (field: string) => OwnershipClause;
+export declare function resolveReadOwnership(ctx: Pick<ExecutorContext, "entity" | "table">, tableName: string, user: SessionUser, db: TenantDb, parentVisibility: ParentVisibilityOption | undefined, gate: {
+    readonly includeDeleted: boolean;
+    readonly narrowTypes: ReadonlySet<string> | undefined;
+}): OwnershipClause;
+export declare function createFieldReadClause(ctx: Pick<ExecutorContext, "entity" | "table">, user: SessionUser): FieldReadClause;
+export type ListWhereBuild = {
+    readonly kind: "empty";
+} | {
+    readonly kind: "ready";
+    readonly where: ListWhere;
+    readonly fieldReadClause: FieldReadClause;
+    readonly searchTruncated: boolean;
+};
+export declare function buildListWhere(ctx: ExecutorContext, payload: ListWherePayload, user: SessionUser, db: TenantDb, runtimeOptions: ListRuntimeOptions | undefined): Promise<ListWhereBuild>;

package/dist/db/event-store-executor-read-where.js

@@ -0,0 +1,81 @@
+import { buildOwnershipClause, combineClauses, normalizeAccessEntry, } from "../engine/ownership.js";
+import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
+import { appendShiftedClause, applyListFilter, collectListFilters, deriveParentNarrowTypes, } from "./event-store-executor-read-filter.js";
+import { applyListSearch } from "./event-store-executor-read-search.js";
+import { buildParentRefClause } from "./parent-ref-clause.js";
+import { physicalColumnName } from "./table-builder.js";
+import { schemaTableName } from "./table-introspection.js";
+// H.2 — entity-level read ownership, AND-ed with the parent-ref read-gate
+// (join-row entities derive their visibility from a host row's own read path —
+// see db/parent-ref-clause.ts). `empty` means there's no row the user could ever see.
+export function resolveReadOwnership(ctx, tableName, user, db, parentVisibility, gate) {
+    const parentClause = buildParentRefClause(ctx.entity, ctx.table, tableName, user, db, parentVisibility, gate);
+    return combineClauses(buildOwnershipClause(user, ctx.entity.access?.read, ctx.table), parentClause);
+}
+// Replicates TenantDb's readWhere semantics for the raw list SQL.
+function appendTenantAndSoftDeleteScope(where, ctx, db, includeDeleted) {
+    if (ctx.table["tenantId"] !== undefined && db.mode === "tenant") {
+        where.params.push(db.tenantId, SYSTEM_TENANT_ID);
+        where.whereSql.push(`${where.colSql("tenantId")} IN ($${where.params.length - 1}, $${where.params.length})`);
+    }
+    if (ctx.softDelete && ctx.table["isDeleted"] && !includeDeleted) {
+        where.whereSql.push(`${where.colSql("isDeleted")} = FALSE`);
+    }
+}
+// Field-level read access gates filtering, sorting and aggregating the same way it
+// gates the projected row: a caller who cannot read a field must not be
+// able to probe its values through result counts, ordering or sums.
+// Built before the search step — a searchable-reference clause is the
+// same probe surface as a filter/sort and must be gated the same way,
+// before the reference-match query even runs.
+export function createFieldReadClause(ctx, user) {
+    return (field) => buildOwnershipClause(user, normalizeAccessEntry(ctx.entity.fields[field]?.access?.read), ctx.table);
+}
+// One WHERE for the row page, its COUNT and the aggregate: ownership, search,
+// tenant/soft-delete scope and filters, so all of them see the same rows.
+// `empty` means no row can match — callers skip the query.
+export async function buildListWhere(ctx, payload, user, db, runtimeOptions) {
+    const { table, entity, entityName, searchAdapter, streamTenantFor } = ctx;
+    const tableName = String(schemaTableName(table));
+    const includeDeleted = runtimeOptions?.includeDeleted === true;
+    // Decide before touching search or the DB: an `empty` ownership skips both paths.
+    const ownership = resolveReadOwnership(ctx, tableName, user, db, runtimeOptions?.parentVisibility, {
+        includeDeleted,
+        narrowTypes: deriveParentNarrowTypes(entity, payload),
+    });
+    if (ownership.kind === "empty")
+        return { kind: "empty" };
+    const where = {
+        whereSql: [],
+        params: [],
+        colSql: (field) => `"${physicalColumnName(table, field)}"`,
+    };
+    const fieldReadClause = createFieldReadClause(ctx, user);
+    let searchTruncated = false;
+    if (payload.search) {
+        // The build-time options.searchAdapter takes precedence; use the runtime override
+        // as a fallback because defaultEntityQueryHandler receives the search adapter only
+        // at runtime, when createEventStoreExecutor has no server context yet.
+        const search = await applyListSearch({
+            searchTerm: payload.search,
+            searchAdapter: searchAdapter ?? runtimeOptions?.searchAdapter,
+            entityName,
+            table,
+            referenceSearch: runtimeOptions?.referenceSearch,
+            fieldReadClause,
+            streamTenantFor,
+            user,
+            db,
+        }, where);
+        if (search.kind === "noMatches")
+            return { kind: "empty" };
+        searchTruncated = search.searchTruncated;
+    }
+    appendTenantAndSoftDeleteScope(where, ctx, db, includeDeleted);
+    if (ownership.kind === "sql")
+        appendShiftedClause(where, ownership);
+    for (const f of collectListFilters(payload)) {
+        applyListFilter(where, f, table, entity, fieldReadClause);
+    }
+    return { kind: "ready", where, fieldReadClause, searchTruncated };
+}

package/dist/db/event-store-executor-read.d.ts

@@ -1,10 +1,3 @@
 import type { EventStoreExecutor } from "./event-store-executor.ts";
-import { type ExecutorContext } from "./event-store-executor-context.ts";
-export declare function resolveListPagination(payload: {
-    readonly limit?: unknown;
-    readonly offset?: unknown;
-}): {
-    readonly limit: number;
-    readonly offset: number;
-};
-export declare function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor, "list" | "detail">;
+import type { ExecutorContext } from "./event-store-executor-context.ts";
+export declare function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor, "list" | "detail" | "aggregate">;