@cosmicdrift/kumiko-framework 0.387.0 → 0.388.0

package/dist/db/where-clause.js

@@ -0,0 +1,236 @@
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { computeBlindIndex, configuredBlindIndexKey } from "../crypto/blind-index.js";
+import { quoteIdent } from "../crypto/ciphertext-pattern.js";
+import { prepareJsonbValue, prepareValue } from "./driver-value-preparation.js";
+function isJsonTextMatchList(value) {
+    return Array.isArray(value);
+}
+function isWhereOperator(v) {
+    if (v === null || typeof v !== "object" || Array.isArray(v))
+        return false;
+    // Don't false-positive on Date / Temporal / other domain-objects.
+    // WhereOperator is plain object literal with at most these keys.
+    const keys = Object.keys(v);
+    if (keys.length === 0)
+        return false;
+    return keys.every((key) => Object.hasOwn(OPERATOR_EMITTERS, key));
+}
+function isJsonbScalar(value) {
+    return value !== null && typeof value !== "object";
+}
+function valueList(target, values) {
+    return values
+        .map((v) => {
+        const p = prepareValue(v, target.pgType);
+        return p.kind === "literal" ? p.literal : `${target.bind(p.bound)}${p.sql}`;
+    })
+        .join(", ");
+}
+// multiSelect (and any other jsonb-array-of-scalars column) stores an
+// array — a filter value is one option, not the whole array, so eq/ne/in
+// must check array containment (`@>`) instead of scalar `=`/`<>`/`IN`
+// against the jsonb column, which Postgres rejects outright.
+// Mirrors applyMultiSelectFilter in event-store-executor-read-filter.ts — keep in lock-step.
+function jsonbContainsAny(target, candidates) {
+    const { column, ref, bind } = target;
+    if (candidates.length === 0)
+        return "FALSE";
+    const parts = [];
+    for (const v of candidates) {
+        const p = prepareJsonbValue([v]);
+        // prepareJsonbValue never returns kind:"literal" (only prepareValue's
+        // isSqlExpression branch does) — narrow anyway, PreparedValue is a union.
+        if (p && p.kind === "param") {
+            parts.push(`${ref(column)} @> ${bind(p.bound)}${p.sql}`);
+        }
+        // A jsonb column holding the scalar itself is never `@>` an array of it.
+        if (isJsonbScalar(v)) {
+            parts.push(`${ref(column)} = ${bind(JSON.stringify(v))}::text::jsonb`);
+        }
+    }
+    return parts.length > 0 ? `(${parts.join(" OR ")})` : "FALSE";
+}
+function isValidJsonTextMatch(match) {
+    if (match === null || typeof match !== "object")
+        return false;
+    const keys = propertyOf(match, "keys");
+    return (Array.isArray(keys) &&
+        keys.length > 0 &&
+        keys.every((k) => typeof k === "string") &&
+        typeof propertyOf(match, "eq") === "string");
+}
+function jsonTextMatchCondition(target, match) {
+    const { column, ref, bind } = target;
+    if (!isValidJsonTextMatch(match)) {
+        throw new Error(`where: jsonText on column "${column}" needs non-empty string keys and a string eq`);
+    }
+    const lookups = match.keys.map((key) => `${ref(column)}->>${bind(key)}::text`);
+    const lhs = lookups.length === 1 ? lookups[0] : `COALESCE(${lookups.join(", ")})`;
+    return `(${lhs} = ${bind(match.eq)})`;
+}
+function emitJsonText(target, operator) {
+    const { column, pgType } = target;
+    const operand = operator.jsonText;
+    if (operand === undefined)
+        return undefined;
+    if (Object.keys(operator).length > 1) {
+        throw new Error(`where: jsonText on column "${column}" cannot be combined with other operators`);
+    }
+    if (pgType !== "jsonb") {
+        throw new Error(`where: jsonText requires a jsonb column, "${column}" is ${pgType}`);
+    }
+    const matches = isJsonTextMatchList(operand) ? operand : [operand];
+    if (matches.length === 0)
+        return "FALSE";
+    return matches.map((match) => jsonTextMatchCondition(target, match)).join(" AND ");
+}
+function comparisonCondition(target, symbol, operand) {
+    const { column, pgType, ref, bind } = target;
+    const p = prepareValue(operand, pgType);
+    return p.kind === "literal"
+        ? `${ref(column)} ${symbol} ${p.literal}`
+        : `${ref(column)} ${symbol} ${bind(p.bound)}${p.sql}`;
+}
+function comparisonEmitter(key, symbol) {
+    return (target, operator) => {
+        const operand = operator[key];
+        if (operand === undefined)
+            return undefined;
+        // Mirrors applyMultiSelectFilter: ordering/pattern ops have no meaning on a jsonb
+        // option array (`like` would crash as `jsonb ~~ jsonb`), so match nothing.
+        if (target.pgType === "jsonb")
+            return "FALSE";
+        return comparisonCondition(target, symbol, operand);
+    };
+}
+// Mirrors applyMultiSelectFilter: an array `ne` means "does not contain all of these".
+function jsonbNotEqualCondition(target, operand) {
+    const { column, ref, bind } = target;
+    if (Array.isArray(operand)) {
+        if (operand.length === 0)
+            return "FALSE";
+        const p = prepareJsonbValue(operand);
+        if (p && p.kind === "param") {
+            return `(${ref(column)} IS NULL OR NOT (${ref(column)} @> ${bind(p.bound)}${p.sql}))`;
+        }
+    }
+    if (isJsonbScalar(operand)) {
+        const p = prepareJsonbValue([operand]);
+        if (p && p.kind === "param") {
+            return `(${ref(column)} IS NULL OR NOT (${ref(column)} @> ${bind(p.bound)}${p.sql} OR ${ref(column)} = ${bind(JSON.stringify(operand))}::text::jsonb))`;
+        }
+    }
+    return undefined;
+}
+function emitNotEqual(target, operator) {
+    const operand = operator.ne;
+    if (operand === undefined)
+        return undefined;
+    if (operand === null && Object.keys(operator).length === 1) {
+        return `${target.ref(target.column)} IS NOT NULL`;
+    }
+    if (target.pgType === "jsonb") {
+        const jsonbCondition = jsonbNotEqualCondition(target, operand);
+        if (jsonbCondition !== undefined)
+            return jsonbCondition;
+    }
+    return comparisonCondition(target, "<>", operand);
+}
+function emitIn(target, operator) {
+    const operand = operator.in;
+    if (!Array.isArray(operand))
+        return undefined;
+    if (target.pgType === "jsonb")
+        return jsonbContainsAny(target, operand);
+    if (operand.length === 0)
+        return "FALSE";
+    return `${target.ref(target.column)} IN (${valueList(target, operand)})`;
+}
+function emitNotIn(target, operator) {
+    const operand = operator.notIn;
+    if (!Array.isArray(operand))
+        return undefined;
+    if (target.pgType === "jsonb") {
+        throw new Error(`where: notIn is not supported on jsonb column "${target.column}"`);
+    }
+    if (operand.length === 0)
+        return "TRUE";
+    return `${target.ref(target.column)} NOT IN (${valueList(target, operand)})`;
+}
+// Insertion order is the SQL emission order. jsonText comes first so its "cannot be combined" error wins over any other
+// operator's error; the rest keep the historical order gt, gte, lt, lte, ne, like, in, notIn.
+const OPERATOR_EMITTERS = {
+    jsonText: emitJsonText,
+    gt: comparisonEmitter("gt", ">"),
+    gte: comparisonEmitter("gte", ">="),
+    lt: comparisonEmitter("lt", "<"),
+    lte: comparisonEmitter("lte", "<="),
+    ne: emitNotEqual,
+    like: comparisonEmitter("like", "LIKE"),
+    in: emitIn,
+    notIn: emitNotIn,
+};
+function operatorConditions(target, operator) {
+    const conditions = [];
+    for (const emit of Object.values(OPERATOR_EMITTERS)) {
+        const condition = emit(target, operator);
+        if (condition !== undefined)
+            conditions.push(condition);
+    }
+    return conditions;
+}
+// Blind-index OR rewrite: if the column has a bidx
+// counterpart (suffix convention `<col>_bidx`, framework-reserved)
+// and a key is configured, equality matches both arms —
+// plaintext legacy rows via the plaintext arm, encrypted rows
+// via the HMAC. The `kumiko-pii:` prefix on ciphertexts makes
+// a random match on the plaintext arm practically impossible.
+function equalityCondition(target, value) {
+    const { info, column, pgType, ref, bind } = target;
+    const p = prepareValue(value, pgType);
+    if (p.kind === "literal")
+        return `${ref(column)} = ${p.literal}`;
+    const bidxKey = configuredBlindIndexKey();
+    const bidxCol = `${column}_bidx`;
+    if (bidxKey !== undefined &&
+        typeof value === "string" &&
+        !column.endsWith("_bidx") &&
+        info.hasColumn(bidxCol)) {
+        return `(${ref(column)} = ${bind(p.bound)} OR ${ref(bidxCol)} = ${bind(computeBlindIndex(bidxKey, value))})`;
+    }
+    return `${ref(column)} = ${bind(p.bound)}${p.sql}`;
+}
+function arrayCondition(target, values) {
+    if (values.length === 0)
+        return "FALSE";
+    if (target.pgType === "jsonb")
+        return jsonbContainsAny(target, values);
+    return `${target.ref(target.column)} IN (${valueList(target, values)})`;
+}
+function conditionsForValue(target, value) {
+    if (value === null)
+        return [`${target.ref(target.column)} IS NULL`];
+    if (Array.isArray(value))
+        return [arrayCondition(target, value)];
+    if (isWhereOperator(value))
+        return operatorConditions(target, value);
+    if (target.pgType === "jsonb" && isJsonbScalar(value)) {
+        return [jsonbContainsAny(target, [value])];
+    }
+    return [equalityCondition(target, value)];
+}
+export function buildWhereClause(info, where, startIndex, qualifier) {
+    const values = [];
+    // Single place that renders a column reference, so a join qualifier reaches
+    // every arm (blind index, jsonb containment, IS NULL, jsonText) alike.
+    const ref = (column) => qualifier === undefined ? quoteIdent(column) : `${quoteIdent(qualifier)}.${quoteIdent(column)}`;
+    const bind = (value) => {
+        values.push(value);
+        return `$${startIndex + values.length - 1}`;
+    };
+    const conditions = Object.entries(where).flatMap(([field, value]) => {
+        const column = info.columnOf(field);
+        return conditionsForValue({ info, column, pgType: info.pgTypeOf(column), ref, bind }, value);
+    });
+    return { sqlText: conditions.join(" AND "), values };
+}

package/dist/derivatives/delete-stored-file.js

@@ -56,6 +56,7 @@ export async function deleteStoredFileAndDerivatives(originalKey, store, errorCo
         ...(await listDerivativeKeys(originalKey, store, errorContext)),
     ];
     const failedKeys = [];
+    const log = createFallbackLogger(errorContext);
     for (const key of keysToDelete) {
         try {
             assertSafeStorageKey(key);
@@ -63,7 +64,7 @@ export async function deleteStoredFileAndDerivatives(originalKey, store, errorCo
         }
         catch (err) {
             failedKeys.push(key);
-            createFallbackLogger(errorContext).warn("storage delete failed", {
+            log.warn("storage delete failed", {
                 key,
                 error: err instanceof Error ? err.message : String(err),
             });

package/dist/engine/boot-validator/boot-check.js

@@ -13,7 +13,7 @@ export function validateFeatureBootChecks(features) {
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
-                throw new Error(`[Feature ${feature.name}] r.bootCheck failed: ${message}. Fix the condition this check reports.`);
+                throw new Error(`[Feature ${feature.name}] r.bootCheck failed: ${message}`);
             }
         }
     }

package/dist/engine/boot-validator/detail-screens.js

@@ -1,8 +1,8 @@
 import { qualifyEntityName } from "../qualified-name.js";
-import { findEntityFeature } from "./screens.js";
+import { findEntityFeature } from "./screens-kind-shared.js";
 // Entity name → the one screen that declares detailFor: "<entity>". Built
 // once, up front (before the per-feature validateScreens loop) so both this
-// module's own uniqueness check AND rowAction entity-targets (in screens.ts)
+// module's own uniqueness check AND rowAction entity-targets (in screens-actions.ts)
 // resolve against the same map instead of re-walking every feature's
 // screens twice.
 export function collectDetailForScreens(features, featureMap) {

package/dist/engine/boot-validator/entity-handler.d.ts

@@ -9,6 +9,7 @@ export declare function validateHandlerAccess(feature: FeatureDefinition): void;
 export declare function validateAdditionalRateLimits(featureName: string, handlerName: string, handler: FeatureDefinition["writeHandlers"][string]): void;
 export declare function validatePerCommandTransaction(featureName: string, handlerName: string, handler: FeatureDefinition["writeHandlers"][string]): void;
 export declare function validateTenantlessAnonymous(featureName: string, handlerName: string, handler: FeatureDefinition["writeHandlers"][string]): void;
+export declare function validateRateLimitCost(featureName: string, handlerName: string, handler: FeatureDefinition["writeHandlers"][string]): void;
 export declare function validateRateLimitDisabledReason(featureName: string, kind: "write" | "query" | "stream", handlerName: string, rateLimit: FeatureDefinition["writeHandlers"][string]["rateLimit"]): void;
 export declare function validateRateLimitBucketList(featureName: string, kind: "write" | "query" | "stream", handlerName: string, rateLimit: FeatureDefinition["writeHandlers"][string]["rateLimit"]): void;
 export declare function validateNoAllRoleInHandlerAccess(featureName: string, kind: "write" | "query" | "stream", handlerName: string, access: NonNullable<FeatureDefinition["writeHandlers"][string]["access"]>): void;

package/dist/engine/boot-validator/entity-handler.js

@@ -139,6 +139,7 @@ export function validateHandlerAccess(feature) {
     for (const [name, handler] of Object.entries(feature.writeHandlers)) {
         validateTenantlessAnonymous(feature.name, name, handler);
         validateAdditionalRateLimits(feature.name, name, handler);
+        validateRateLimitCost(feature.name, name, handler);
         validatePerCommandTransaction(feature.name, name, handler);
     }
 }
@@ -235,6 +236,22 @@ export function validateTenantlessAnonymous(featureName, handlerName, handler) {
             `tenant/user bucket, so one caller could exhaust it for all. Use ${IP_SCOPED_RATE_LIMIT_PER.map((allowed) => `"${allowed}"`).join(" or ")}.`);
     }
 }
+export function validateRateLimitCost(featureName, handlerName, handler) {
+    // skip: no payload-derived cost declared
+    if (!handler.rateLimitCost)
+        return;
+    if (handler.rateLimit === undefined || isRateLimitDisabled(handler.rateLimit)) {
+        throw new Error(`write handler "${featureName}:write:${handlerName}" declares rateLimitCost without an active rateLimit — ` +
+            `the cost is booked on the rateLimit buckets, so declare rateLimit or drop rateLimitCost.`);
+    }
+    const isAnonymous = "roles" in handler.access && handler.access.roles.includes("anonymous");
+    const hasIpBucket = declaredRateLimitOptions(handler.rateLimit).some(({ per }) => IP_SCOPED_RATE_LIMIT_PER.includes(per));
+    if (isAnonymous || hasIpBucket) {
+        throw new Error(`write handler "${featureName}:write:${handlerName}" declares rateLimitCost on an anonymous or ip-limited handler — ` +
+            `rateLimitCost books after the parse, so such a handler would lose its pre-parse protection against junk floods. ` +
+            `Bulk handlers are authenticated: use a user/tenant bucket and drop "anonymous", or drop rateLimitCost.`);
+    }
+}
 export function validateRateLimitDisabledReason(featureName, kind, handlerName, rateLimit) {
     // skip: rate limit isn't disabled, so no reason is required
     if (!isRateLimitDisabled(rateLimit))

package/dist/engine/boot-validator/form-derivations.js

@@ -3,15 +3,46 @@ import { parseQn } from "../qualified-name.js";
 import { formDerivationsOfSchema } from "../with-form-derivations.js";
 const NUMERIC_FORM_FIELD_TYPES = ["money", "number", "decimal"];
 const NUMERIC_SUB_FIELD_TYPES = ["money", "number", "decimal"];
+function isMoneyType(type) {
+    return type === "money";
+}
+// Money operands are computed in minor units, number/decimal in major units: mixing them
+// silently scales the result by 100 or 10000.
+function validateUnitCompatibility({ prefix, screen, target }, derivation) {
+    const targetIsMoney = isMoneyType(screen.fields[target]?.type);
+    const moneyFlags = derivation.from.map((source) => isMoneyType(screen.fields[source]?.type));
+    const moneyCount = moneyFlags.filter(Boolean).length;
+    if (derivation.op === "sum" || derivation.op === "subtract") {
+        if (moneyCount !== 0 && moneyCount !== moneyFlags.length) {
+            throw new Error(`${prefix}.${target}: "${derivation.op}" sources must be all money or all number/decimal.`);
+        }
+        if (moneyCount > 0 !== targetIsMoney) {
+            throw new Error(`${prefix}.${target}: a "${derivation.op}" over ${moneyCount > 0 ? "money" : "number/decimal"} sources needs a ${moneyCount > 0 ? "money" : "number/decimal"} target.`);
+        }
+        // skip: sum/subtract fully validated above.
+        return;
+    }
+    if (moneyCount > 1 || (derivation.op === "percent" && moneyFlags[1] === true)) {
+        throw new Error(`${prefix}.${target}: "${derivation.op}" takes at most one money source${derivation.op === "percent" ? " (the base, not the rate)" : ""}.`);
+    }
+    if ((moneyCount === 1) !== targetIsMoney) {
+        throw new Error(`${prefix}.${target}: the target must be money exactly when a "${derivation.op}" source is money.`);
+    }
+}
 function validateFromList({ prefix, screen, target }, derivation) {
     if (derivation.op === "percent" && derivation.from.length !== 2) {
         throw new Error(`${prefix}.${target}: "percent" needs exactly two sources (base, rate).`);
     }
     for (const source of derivation.from) {
-        if (!(source in screen.fields)) {
+        const sourceField = screen.fields[source];
+        if (sourceField === undefined) {
             throw new Error(`${prefix}.${target}: unknown source field "${source}". Name a field of this screen.`);
         }
+        if (!NUMERIC_FORM_FIELD_TYPES.includes(sourceField.type)) {
+            throw new Error(`${prefix}.${target}: source "${source}" must be money, number or decimal, not "${sourceField.type}".`);
+        }
     }
+    validateUnitCompatibility({ prefix, screen, target }, derivation);
 }
 function validateListSum(check, derivation) {
     const { prefix, screen, target } = check;
@@ -26,6 +57,9 @@ function validateListSum(check, derivation) {
     if (cellType === undefined || !NUMERIC_SUB_FIELD_TYPES.includes(cellType)) {
         throw new Error(`${prefix}.${target}: "${derivation.cell}" must be a money, number or decimal sub-field of "${derivation.list}".`);
     }
+    if (isMoneyType(cellType) !== isMoneyType(screen.fields[target]?.type)) {
+        throw new Error(`${prefix}.${target}: a listSum of a ${isMoneyType(cellType) ? "money" : "number/decimal"} cell needs a ${isMoneyType(cellType) ? "money" : "number/decimal"} target.`);
+    }
     const { whenEmpty } = derivation;
     // skip: whenEmpty is optional
     if (whenEmpty === undefined)

package/dist/engine/boot-validator/i18n-keys.js

@@ -94,9 +94,11 @@ export function validateTranslationLocaleConsistency(features) {
     }
 }
 export function validateRequiredLocales(features, requiredLocales) {
-    const gaps = findRequiredLocaleGaps(features, requiredLocales ?? []);
-    if (gaps.length > 0) {
+    const gaps = requiredLocales === undefined || requiredLocales.length === 0
+        ? []
+        : findRequiredLocaleGaps(features, requiredLocales);
+    if (requiredLocales !== undefined && gaps.length > 0) {
         const lines = gaps.map((gap) => `[i18n] Feature "${gap.featureName}": translation key "${gap.key}" is missing required locale(s) ${gap.missingLocales.join(", ")}.`);
-        throw new Error(`${lines.join("\n")}\nThe app requires locales [${(requiredLocales ?? []).join(", ")}] for every translation key; load the matching locale package or add the missing translations.`);
+        throw new Error(`${lines.join("\n")}\nThe app requires locales [${requiredLocales.join(", ")}] for every translation key; load the matching locale package or add the missing translations.`);
     }
 }

package/dist/engine/boot-validator/index.js

@@ -2,6 +2,7 @@ import { validateEntityFieldEncryptionAvailable } from "../../db/entity-field-en
 import { dedupeFeatures } from "../dedupe-features.js";
 import { FILE_STORAGE_PROVIDER_ENV } from "../extension-names.js";
 import { QnTypes, qualifyEntityName } from "../qualified-name.js";
+import { validateProjectionAllowlist } from "../validate-projection-allowlist.js";
 import { validateAccessDeclarations } from "./access-declarations.js";
 import { warnOnUniqueAccessRoles } from "./access-roles.js";
 import { validateActionWiring, validateFieldWiring } from "./action-wiring.js";
@@ -238,6 +239,7 @@ export function validateBoot(rawFeatures, options) {
     validateGdprStoragePersistence(features);
     validateGlobalTenancyEntities(features);
     validateFeatureBootChecks(features);
+    validateProjectionAllowlist(features);
     if (hasEncryptedFields) {
         // Availability check, not env-presence: eagerly building the keyring
         // catches malformed keys (wrong length, bad base64) at boot instead of