@cosmicdrift/kumiko-framework 0.337.1 → 0.339.0

package/dist/db/blind-index-cleanup.d.ts

@@ -3,4 +3,5 @@ import type { DbRunner } from "./connection.js";
 export declare function nullBlindIndexesForSubject(db: DbRunner, features: ReadonlyMap<string, FeatureDefinition>, subjectKey: string): Promise<void>;
 export declare function subjectRowExistsInTenant(db: DbRunner, features: ReadonlyMap<string, FeatureDefinition>, subjectId: string, tenantId: string): Promise<boolean>;
 export declare function recordRowExistsInTenant(db: DbRunner, features: ReadonlyMap<string, FeatureDefinition>, entityName: string, recordId: string, tenantId: string): Promise<boolean>;
+export declare function recordEventsOwnedExclusivelyByTenant(db: DbRunner, aggregateType: string, aggregateId: string, tenantId: string): Promise<boolean>;
 export declare function recordRowOwningTenantId(db: DbRunner, features: ReadonlyMap<string, FeatureDefinition>, entityName: string, recordId: string): Promise<string | undefined>;

package/dist/db/blind-index-cleanup.js

@@ -131,6 +131,17 @@ export async function recordRowExistsInTenant(db, features, entityName, recordId
     const rows = await executeRawQueryRead(db, `SELECT 1 FROM ${quoteIdent(tableName)} WHERE id = $1 AND tenant_id = $2 LIMIT 1`, [recordId, tenantId]);
     return rows.length > 0;
 }
+// Provenance fallback for record subjects whose projection row is gone (hard
+// delete) or that have no registered entity at all (custom aggregates): the
+// event stream still names the owning tenant. The unique index is per tenant
+// and the subject key is global, so another tenant could open a stream under
+// the same aggregate id; any foreign event voids the proof.
+export async function recordEventsOwnedExclusivelyByTenant(db, aggregateType, aggregateId, tenantId) {
+    const rows = await executeRawQueryRead(db, `SELECT 1 FROM "kumiko_events" WHERE aggregate_type = $1 AND aggregate_id = $2::uuid AND tenant_id = $3::uuid
+       AND NOT EXISTS (SELECT 1 FROM "kumiko_events" WHERE aggregate_type = $1 AND aggregate_id = $2::uuid AND tenant_id <> $3::uuid)
+     LIMIT 1`, [aggregateType, aggregateId, tenantId]);
+    return rows.length > 0;
+}
 // Owning tenant of a record subject's row, for callers that must evaluate
 // tenant-scoped policy for the row's real owner (not the acting user's tenant).
 export async function recordRowOwningTenantId(db, features, entityName, recordId) {

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

@@ -258,7 +258,15 @@ function isSoftDeletedTargetHidden(targetEntity, targetTable) {
 // unscoped SQL, a match in a foreign tenant must never surface a row here
 // (fw#2660's hard constraint). Mirrors the main table's own tenant filter
 // (see the `table["tenantId"]` check further down in list()).
-async function resolveReferenceMatchesViaIlike(descriptor, searchTerm, targetEntity, targetTable, targetTableName, db) {
+async function resolveReferenceMatchesViaIlike(descriptor, searchTerm, targetEntity, targetTable, targetTableName, user, db) {
+    // The label must not leak through match counts: a viewer who cannot read the
+    // target row or its label field would otherwise probe names by searching.
+    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 labelCol = physicalColumnName(targetTable, descriptor.labelField);
     const subParams = [`%${escapeLikePattern(searchTerm)}%`];
     let tenantClause = "";
@@ -266,12 +274,19 @@ async function resolveReferenceMatchesViaIlike(descriptor, searchTerm, targetEnt
         subParams.push(db.tenantId, SYSTEM_TENANT_ID);
         tenantClause = ` AND "${physicalColumnName(targetTable, "tenantId")}" IN ($2, $3)`;
     }
+    let ownershipClause = "";
+    if (ownership.kind === "sql") {
+        const shifted = shiftParams({ sqlText: ownership.sqlText, params: ownership.params }, subParams.length);
+        ownershipClause = ` AND ${shifted.sqlText}`;
+        for (const p of shifted.params)
+            subParams.push(p);
+    }
     const deletedClause = isSoftDeletedTargetHidden(targetEntity, targetTable)
         ? ` AND "${physicalColumnName(targetTable, "isDeleted")}" = FALSE`
         : "";
     // ::text cast covers a non-text labelField (e.g. a number/select column
     // used as label) — Postgres has no ILIKE for those types otherwise.
-    const sql = `SELECT "id" FROM "${targetTableName}" WHERE ("${labelCol}")::text ILIKE $1${tenantClause}${deletedClause} ` +
+    const sql = `SELECT "id" FROM "${targetTableName}" WHERE ("${labelCol}")::text ILIKE $1${tenantClause}${ownershipClause}${deletedClause} ` +
         `LIMIT ${MAX_REFERENCE_SEARCH_IDS + 1}`;
     const rows = await executeRawQueryRead(tenantDbRunner(db), sql, subParams);
     if (rows.length === 0 || rows.length > MAX_REFERENCE_SEARCH_IDS) {
@@ -328,7 +343,7 @@ async function resolveReferenceMatches(descriptor, searchTerm, resolveEntity, db
     const targetTable = referenceTargetTable(descriptor.targetEntityName, targetEntity);
     const targetTableName = String(targetTable[KUMIKO_NAME_SYMBOL]);
     if (!isSensitiveLabelField(targetEntity, descriptor.labelField)) {
-        return resolveReferenceMatchesViaIlike(descriptor, searchTerm, targetEntity, targetTable, targetTableName, db);
+        return resolveReferenceMatchesViaIlike(descriptor, searchTerm, targetEntity, targetTable, targetTableName, user, db);
     }
     if (!hasSearchablePlaintext(targetEntity, descriptor.labelField)) {
         // skip: no plaintext anywhere to match — boot rejects this normally,

package/dist/db/index.d.ts

@@ -1,5 +1,5 @@
 export { assertExistsIn } from "./assert-exists-in.js";
-export { nullBlindIndexesForSubject, recordRowExistsInTenant, recordRowOwningTenantId, subjectRowExistsInTenant, } from "./blind-index-cleanup.js";
+export { nullBlindIndexesForSubject, recordEventsOwnedExclusivelyByTenant, recordRowExistsInTenant, recordRowOwningTenantId, subjectRowExistsInTenant, } from "./blind-index-cleanup.js";
 export { collectTableMetas } from "./collect-table-metas.js";
 export { flattenCompoundTypes, rehydrateCompoundTypes } from "./compound-types.js";
 export { seedConfigValues } from "./config-seed.js";

package/dist/db/index.js

@@ -1,5 +1,5 @@
 export { assertExistsIn } from "./assert-exists-in.js";
-export { nullBlindIndexesForSubject, recordRowExistsInTenant, recordRowOwningTenantId, subjectRowExistsInTenant, } from "./blind-index-cleanup.js";
+export { nullBlindIndexesForSubject, recordEventsOwnedExclusivelyByTenant, recordRowExistsInTenant, recordRowOwningTenantId, subjectRowExistsInTenant, } from "./blind-index-cleanup.js";
 export { collectTableMetas } from "./collect-table-metas.js";
 export { flattenCompoundTypes, rehydrateCompoundTypes } from "./compound-types.js";
 export { seedConfigValues } from "./config-seed.js";

package/dist/db/queries/backfill-pii.js

@@ -300,6 +300,10 @@ export async function backfillEventPiiEncryptionBatch(db, registry, options = {}
                     const value = section[field];
                     if (value === null || value === undefined)
                         continue;
+                    // jsonb PII is not retro-encrypted (consumer wave); a legacy string
+                    // value here would otherwise get the v2 text format into a jsonb column.
+                    if (target.entity.fields[field]?.type === "jsonb")
+                        continue;
                     if (typeof value !== "string")
                         continue;
                     // Already-ciphertext/sentinel fields must never enter owner

package/dist/db/tenant-db.js

@@ -11,7 +11,7 @@ const declaredUnsafeRawRunners = new WeakMap();
 // TenantDb it was handed for its gate. Bound inside createTenantDb so rebound instances
 // (withUnsafeRawGrant, acknowledgeConventionCrossTenant) carry it too.
 const personalDataGates = new WeakMap();
-// Lets createTenantDb(ctx.db.unsafeRaw(reason), ...) inherit the gate. Keyed by a
+// Lets createTenantDb(ctx.db.unsafeRaw(), ...) inherit the gate. Keyed by a
 // per-grant proxy, never the shared pool/tx: tagging that would gate every sibling TenantDb.
 const runnerPersonalDataGates = new WeakMap();
 function gatedRunner(runner, gate) {
@@ -96,9 +96,15 @@ function buildUncheckedSystemDb(db, dbOutsideTransaction, report, gate) {
         }
         return dbOutsideTransaction;
     }
-    function grantedUnsafeRawRunner(reason) {
+    function grantedUnsafeRawRunner(reason, forwardedDeclaredStep) {
         if (gate?.kind === "source-tenant-db") {
-            return unsafeRawForDeclaredStep(db, reason);
+            const sourceRunner = declaredUnsafeRawRunners.get(db);
+            if (!sourceRunner) {
+                throw new InternalError({
+                    message: "createSystemDbView received a TenantDb with no declared unsafeRaw runner bound.",
+                });
+            }
+            return sourceRunner(forwardedDeclaredStep ? reason : undefined);
         }
         if (reason.trim().length === 0) {
             throw new Error("unsafeRaw requires a non-empty reason");
@@ -109,7 +115,8 @@ function buildUncheckedSystemDb(db, dbOutsideTransaction, report, gate) {
                     `${gate.deniedCallerLabel} to allow unsafeRaw.`,
             });
         }
-        report("unsafe-raw", reason);
+        // Engine-forwarded steps carry their own declared reason; a caller-supplied one never reaches the audit trail.
+        report("unsafe-raw", forwardedDeclaredStep ? reason : (gate?.grant?.reason ?? reason));
         const runner = tenantDbRunner(db);
         const personalDataGate = personalDataGates.get(db);
         return personalDataGate ? gatedRunner(runner, personalDataGate) : runner;
@@ -143,7 +150,7 @@ function buildUncheckedSystemDb(db, dbOutsideTransaction, report, gate) {
             report("acknowledge-cross-tenant", reason);
             return db;
         },
-        unsafeRaw: grantedUnsafeRawRunner,
+        unsafeRaw: (reason) => grantedUnsafeRawRunner(reason, false),
         outsideTransaction: {
             assertTenantMatch(tenantId) {
                 if (tenantId !== db.tenantId) {
@@ -163,7 +170,14 @@ function buildUncheckedSystemDb(db, dbOutsideTransaction, report, gate) {
             },
         },
     };
-    declaredUnsafeRawRunners.set(uncheckedSystemDb, grantedUnsafeRawRunner);
+    declaredUnsafeRawRunners.set(uncheckedSystemDb, (declaredStepReason) => {
+        if (declaredStepReason === undefined) {
+            throw new InternalError({
+                message: "A declared unsafeRaw runner on a system db requires the step reason.",
+            });
+        }
+        return grantedUnsafeRawRunner(declaredStepReason, true);
+    });
     if (gate?.kind !== "source-tenant-db") {
         systemDbRebinders.set(uncheckedSystemDb, (grant, deniedCallerLabel) => buildUncheckedSystemDb(withUnsafeRawGrant(db, grant), dbOutsideTransaction && withUnsafeRawGrant(dbOutsideTransaction, grant), report, { kind: "hook-grant", grant, deniedCallerLabel }));
     }
@@ -419,28 +433,26 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
             // @cast-boundary type-brand — GlobalWrites is only present in the type when TTable is not ExecutorOnly; the object above always carries the methods.
         };
     }
-    function grantedUnsafeRawRunner(reason) {
-        if (reason.trim().length === 0) {
-            throw new Error("unsafeRaw requires a non-empty reason");
-        }
+    function grantedUnsafeRawRunner(declaredStepReason) {
         // Ahead of the grant check: a declared escapeHatch must not buy a raw runner here either.
         if (grants?.memberReadOnly) {
             throw memberResolutionReadOnlyDenied();
         }
         if (!hasGrant(grants?.unsafeRaw)) {
             throw new AccessDeniedError({
-                message: 'ctx.db.unsafeRaw(reason): rejected — declare `escapeHatch: { reason: "..." }` on ' +
+                message: 'ctx.db.unsafeRaw(): rejected — declare `escapeHatch: { reason: "..." }` on ' +
                     "the handler or hook to allow unsafeRaw.",
             });
         }
-        report("unsafe-raw", reason);
+        // Engine-forwarded steps carry their own declared reason; otherwise the grant's reason is audited.
+        report("unsafe-raw", declaredStepReason ?? grants?.unsafeRaw?.reason ?? "");
         return personalDataGate ? gatedRunner(db, personalDataGate) : db;
     }
     const tenantDb = {
         tenantId,
         mode,
         global: globalTable,
-        unsafeRaw: grantedUnsafeRawRunner,
+        unsafeRaw: () => grantedUnsafeRawRunner(),
         selectMany(table, where, options) {
             const filter = readWhere(table, where);
             return withDbSpan("select", table, async () => bunSelectMany(db, table, filter, options));

package/dist/engine/boot-validator/access-declarations.js

@@ -1,3 +1,4 @@
+import { escapeHatchGrantsProblem } from "@cosmicdrift/kumiko-types/handlers";
 import { accessAllowsAnonymous, declaredPersonalData, personalFieldNames, } from "../personal-data-fields.js";
 import { ANONYMOUS_ROLE } from "../system-user.js";
 import { collectZodObjectKeys } from "./zod-shape.js";
@@ -48,13 +49,18 @@ function validateOpenToAllReason(feature, kind, handlerName, access) {
         "authenticated user may call this handler. `{ openToAll: true }` is no longer accepted.");
 }
 function validateEscapeHatchReason(feature, kind, handlerName, escapeHatch) {
-    // skip: no escapeHatch declared, or its reason is already non-empty
-    if (!escapeHatch || escapeHatch.reason.trim().length > 0)
-        return;
-    throw new Error(`[Feature ${feature.name}] ${kind} handler "${handlerName}" declares ` +
-        `{ escapeHatch: { reason: "" } } — the reason must be a non-empty string ` +
-        "explaining why this handler needs db.global() write access, a SYSTEM identity switch " +
-        "or a cross-tenant ctx.queryProjection({ unsafeAllTenants: true }) read.");
+    if (escapeHatch) {
+        const grantsProblem = escapeHatchGrantsProblem(escapeHatch);
+        if (grantsProblem !== undefined) {
+            throw new Error(`[Feature ${feature.name}] ${kind} handler "${handlerName}" declares an invalid escapeHatch — ${grantsProblem}`);
+        }
+        if (escapeHatch.reason.trim().length === 0) {
+            throw new Error(`[Feature ${feature.name}] ${kind} handler "${handlerName}" declares ` +
+                `{ escapeHatch: { reason: "" } } — the reason must be a non-empty string ` +
+                "explaining why this handler needs db.global() write access, a SYSTEM identity switch " +
+                "or a cross-tenant ctx.queryProjection({ unsafeAllTenants: true }) read.");
+        }
+    }
 }
 function validatePersonalDataOnlyOnWrite(feature, kind, handlerName, access) {
     // skip: write handlers may declare personalData, or it wasn't declared here

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

@@ -6,6 +6,7 @@ export declare const PII_USER_REFERENCE_NAME_HINTS: ReadonlySet<string>;
 /** Extensions with preSave must target an entity that has mapped write handlers. */
 export declare function validateExtensionPreSaveWiring(features: readonly FeatureDefinition[]): void;
 export declare function validateHandlerAccess(feature: FeatureDefinition): void;
+export declare function validateTenantlessAnonymous(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 validateNoAllRoleInHandlerAccess(featureName: string, kind: "write" | "query" | "stream", handlerName: string, access: NonNullable<FeatureDefinition["writeHandlers"][string]["access"]>): void;
 export declare function validateAnonymousRateLimit(featureName: string, kind: "write" | "query" | "stream", handlerName: string, access: NonNullable<FeatureDefinition["writeHandlers"][string]["access"]>, rateLimit: FeatureDefinition["writeHandlers"][string]["rateLimit"]): void;
@@ -22,3 +23,4 @@ export declare function validateImageVariants(feature: FeatureDefinition): void;
 export declare function validateTransitions(feature: FeatureDefinition): void;
 export declare function validateExtendSchemaCollisions(feature: FeatureDefinition): void;
 export declare function validateDerivedFieldCollisions(feature: FeatureDefinition): void;
+export declare function validateSearchableFieldReadAccess(feature: FeatureDefinition): void;

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

@@ -134,6 +134,25 @@ export function validateHandlerAccess(feature) {
             validateRateLimitDisabledReason(feature.name, kind, name, handler.rateLimit);
         }
     }
+    for (const [name, handler] of Object.entries(feature.writeHandlers)) {
+        validateTenantlessAnonymous(feature.name, name, handler);
+    }
+}
+export function validateTenantlessAnonymous(featureName, handlerName, handler) {
+    // skip: handler does not opt into tenantless anonymous calls
+    if (!handler.tenantlessAnonymous)
+        return;
+    const where = `write handler "${featureName}:write:${handlerName}" declares tenantlessAnonymous`;
+    const { access } = handler;
+    const isAnonymousOnly = "roles" in access && access.roles.length === 1 && access.roles[0] === "anonymous";
+    if (!isAnonymousOnly) {
+        throw new Error(`${where} but its access is not exactly { roles: ["anonymous"] } — a tenantless request ` +
+            `carries no principal beyond the anonymous visitor.`);
+    }
+    if (!handler.rateLimit || isRateLimitDisabled(handler.rateLimit)) {
+        throw new Error(`${where} without a rateLimit — a handler reachable on hosts that resolve no tenant ` +
+            `needs a real upper bound (rateLimit: { per: "ip", ... }); { disabled: true } does not count.`);
+    }
 }
 export function validateRateLimitDisabledReason(featureName, kind, handlerName, rateLimit) {
     // skip: rate limit isn't disabled, so no reason is required
@@ -784,3 +803,29 @@ export function validateDerivedFieldCollisions(feature) {
         }
     }
 }
+// --- Searchable fields with restricted read access ---
+// The search index is tenant-wide, not per-role: `search` matches every
+// searchable field and `filterReadFields` only strips the response afterwards.
+// A role that cannot read the field could still guess its value from match
+// counts, so the combination is rejected until the index can filter per role.
+export function validateSearchableFieldReadAccess(feature) {
+    for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
+        for (const [fieldName, field] of Object.entries(entity.fields)) {
+            if (field.type !== "text")
+                continue;
+            if (!field.searchable)
+                continue;
+            const readAccess = field.access?.read;
+            if (readAccess === undefined)
+                continue;
+            const isUnrestricted = Array.isArray(readAccess)
+                ? readAccess.length === 0
+                : Object.keys(readAccess).length === 0;
+            if (isUnrestricted)
+                continue;
+            throw new Error(`Field "${fieldName}" on entity "${entityName}" cannot be searchable with a restricted ` +
+                "access.read — the search index is not filtered per role, so search matches would leak " +
+                'the value to roles that cannot read it. Drop `searchable`/`find: "fuzzy"` or `access.read`.');
+        }
+    }
+}

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

@@ -9,7 +9,7 @@ import { validateApiExposureMatching, validateExtensionUsages } from "./api-ext.
 import { validateFeatureBootChecks } from "./boot-check.js";
 import { validateCircularDeps, validateConfigKeyAllowPerRequest, validateConfigKeyBacking, validateConfigKeyBounds, validateConfigKeyComputed, validateConfigKeyOptionsQuery, validateConfigKeyPiiEncrypted, validateConfigKeyRequired, validateConfigReads, warnOnToggleableDependencies, } from "./config-deps.js";
 import { collectDetailForScreens } from "./detail-screens.js";
-import { validateDerivedFieldCollisions, validateEmbeddedFields, validateEncryptedFields, validateEntityIndexes, validateEntitySelectOptionsQuery, validateExtendSchemaCollisions, validateExtensionPreSaveWiring, validateFileFields, validateHandlerAccess, validateImageVariants, validateLocatedTimestamps, validateMultiSelectFields, validateMultiStreamProjections, validateReferenceFields, validateTransitions, } from "./entity-handler.js";
+import { validateDerivedFieldCollisions, validateEmbeddedFields, validateEncryptedFields, validateEntityIndexes, validateEntitySelectOptionsQuery, validateExtendSchemaCollisions, validateExtensionPreSaveWiring, validateFileFields, validateHandlerAccess, validateImageVariants, validateLocatedTimestamps, validateMultiSelectFields, validateMultiStreamProjections, validateReferenceFields, validateSearchableFieldReadAccess, validateTransitions, } from "./entity-handler.js";
 import { validateEntityListScreens } from "./entity-list-screens.js";
 import { validateGdprStoragePersistence } from "./gdpr-storage.js";
 import { validateGlobalTenancyEntities } from "./global-tenancy.js";
@@ -118,6 +118,7 @@ export function validateBoot(rawFeatures, options) {
         validateCircularDeps(feature.name, featureMap);
         if (validateEncryptedFields(feature))
             hasEncryptedFields = true;
+        validateSearchableFieldReadAccess(feature);
         if (validateFileFields(feature))
             hasFileFields = true;
         validatePiiAndRetention(feature);

package/dist/engine/boot-validator/pii-retention.js

@@ -12,6 +12,12 @@ const FRAMEWORK_TIMESTAMP_FIELDS = new Set([
 // macht nur den Sanity-Check damit Tippfehler ("30days") frueh sichtbar
 // werden statt erst beim ersten Cleanup-Run.
 const KEEP_FOR_PATTERN = /^\d+[hdwmy]$/;
+const FILE_FIELD_TYPES = new Set([
+    "file",
+    "image",
+    "files",
+    "images",
+]);
 // Excludes subjectRef: its `personal: "ref"` union member structurally
 // forbids `anonymize` (packages/types/src/fields.ts) — #2336.
 function hasAnonymizableSubjectField(annot) {
@@ -65,6 +71,33 @@ function validateWriteOnlyField(featureName, entityName, fieldName, field) {
         }
     }
 }
+// A personal jsonb field is stored as a ciphertext JSON string scalar, so
+// anything that reads inside the column (index, filter, sort, search, jsonb
+// operators/merges such as the custom-fields column) sees only ciphertext.
+const JSONB_PERSONAL_FORBIDDEN_FLAGS = [
+    "sortable",
+    "filterable",
+    "searchable",
+    "lookupable",
+];
+const CUSTOM_FIELDS_COLUMN = "customFields";
+function validatePersonalJsonbField(featureName, entityName, entity, fieldName, field) {
+    const where = `[Feature ${featureName}] Field "${fieldName}" on entity "${entityName}"`;
+    const reason = "a personal jsonb field is stored as a ciphertext string, so nothing inside it can be indexed, filtered, sorted, searched or merged";
+    const flags = field; // @cast-boundary schema-walk
+    for (const flag of JSONB_PERSONAL_FORBIDDEN_FLAGS) {
+        if (flags[flag] !== undefined && flags[flag] !== false) {
+            throw new Error(`${where} combines a personal annotation on a jsonb field with { ${flag} } — ${reason}.`);
+        }
+    }
+    const index = entity.indexes?.find((def) => def.columns.includes(fieldName));
+    if (index) {
+        throw new Error(`${where} is a personal jsonb field used in an entity index — ${reason}. Drop the index or the personal annotation.`);
+    }
+    if (fieldName === CUSTOM_FIELDS_COLUMN) {
+        throw new Error(`${where} is the custom-fields jsonb column — its values are merged and searched per key, which ciphertext cannot support. Drop the personal annotation.`);
+    }
+}
 // --- PII / Subject-Key Annotations + Retention validation ---
 //
 // Drei Klassen von Checks:
@@ -147,6 +180,9 @@ export function validatePiiAndRetention(feature) {
                     throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" combines { sensitive: true } with { searchable: true } — sensitive means ciphertext at rest, never searchable, stripped from event echoes — authorized readers can still read it back (passwords, tokens, tax IDs). Subject-annotated identity fields may be searchable (#1610); sensitive fields may not. To never return the value at all, add { writeOnly: true }.`);
                 }
             }
+            if (field.type === "jsonb" && annotCount > 0) {
+                validatePersonalJsonbField(feature.name, entityName, entity, fieldName, field);
+            }
             if (annot.userOwned) {
                 const ownerName = annot.userOwned.ownerField;
                 if (!ownerName || typeof ownerName !== "string") {
@@ -184,7 +220,11 @@ export function validatePiiAndRetention(feature) {
             const noAnnotation = annotCount === 0 && !annot.allowPlaintext;
             if (noAnnotation) {
                 const lower = fieldName.toLowerCase();
-                if (PII_DIRECT_NAME_HINTS.has(lower)) {
+                if (FILE_FIELD_TYPES.has(field.type)) {
+                    // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+                    console.warn(`[kumiko:boot] [Feature ${feature.name}] File field "${fieldName}" on entity "${entityName}" has no personal annotation. A forget with strategy "delete" then only severs the uploader link and keeps the binary. If the file holds personal data, mark it { personal: "self" } or { personal: { of: "<ownerField>" } }. If it is business data, set { personal: false, reason: "is_business_data" } to silence.`);
+                }
+                else if (PII_DIRECT_NAME_HINTS.has(lower)) {
                     // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
                     console.warn(`[kumiko:boot] [Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has a PII-typical name but no personal annotation. If this is PII, mark it { personal: "self", find: ... }. If business data, set { personal: false, reason: "is_business_data" } to silence.`);
                 }

package/dist/engine/config-helpers.d.ts

@@ -1,4 +1,4 @@
-import type { ConfigBacking, ConfigBounds, ConfigComputedFn, ConfigKeyDefinition, ConfigKeyType, ConfigMask, ConfigSeedDef, ConfigValue, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, OptionsQueryPayload } from "./types/index.js";
+import type { ConfigBacking, ConfigBounds, ConfigComputedFn, ConfigKeyDefinition, ConfigKeyType, ConfigMask, ConfigSeedDef, ConfigValidateFn, ConfigValue, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, OptionsQueryPayload } from "./types/index.js";
 export declare function isEncryptedAtRest(def: Pick<ConfigKeyDefinition, "encrypted" | "backing">): boolean;
 export declare const access: {
     readonly all: readonly string[];
@@ -26,6 +26,7 @@ type ConfigKeyOptions<T extends ConfigKeyType> = {
         flags?: string;
     } : never;
     computed?: ConfigComputedFn<T>;
+    validate?: ConfigValidateFn<T>;
     allowPerRequest?: T extends "text" ? never : boolean;
     required?: boolean;
     env?: string;

package/dist/engine/config-helpers.js

@@ -60,6 +60,7 @@ function createConfigKey(scope, type, opts = {}) {
         bounds: opts.bounds, // @cast-boundary schema-walk
         ...(opts.pattern ? { pattern: opts.pattern } : {}),
         computed: opts.computed,
+        validate: opts.validate,
         ...(opts.allowPerRequest === true ? { allowPerRequest: true } : {}),
         ...(opts.required === true ? { required: true } : {}),
         ...(opts.env ? { env: opts.env } : {}),

package/dist/engine/define-handler.js

@@ -51,6 +51,7 @@ export function defineWriteHandler(def,
         }),
         ...(def.rateLimit && { rateLimit: def.rateLimit }),
         ...(def.escapeHatch && { escapeHatch: def.escapeHatch }),
+        ...(def.tenantlessAnonymous && { tenantlessAnonymous: true }),
     };
     if ("perform" in def && def.perform !== undefined) {
         const performDef = def.perform;

package/dist/engine/extensions/escape-hatch-usage.js

@@ -7,6 +7,8 @@ export function extensionUsageEscapeHatchReason(usage) {
     const escapeHatch = usage.options?.["escapeHatch"];
     if (typeof escapeHatch !== "object" || escapeHatch === null)
         return undefined;
-    const reason = escapeHatch.reason;
+    const { reason, grants } = escapeHatch;
+    if (Array.isArray(grants) && !grants.includes("unsafeRaw"))
+        return undefined;
     return typeof reason === "string" && reason.trim().length > 0 ? reason : undefined;
 }

package/dist/engine/extensions/user-data.d.ts

@@ -30,7 +30,7 @@ export type TenantUserModel = "single-user" | "multi-user";
  * fw#2914 — `db` is a tenant-filtered `TenantDb`, bound to `tenantId`
  * (or the per-user sub-tx in the forget path). Unfiltered access needs
  * `escapeHatch: { reason }` on the `r.useExtension(...)` registration,
- * then `ctx.db.unsafeRaw(reason)`.
+ * then `ctx.db.unsafeRaw()`.
  */
 /**
  * Minimal storage surface a file-aware forget hook needs to erase binaries.

package/dist/engine/feature-ast/extractors/handlers.js

@@ -32,6 +32,7 @@ const WRITE_HANDLER_KEY_KINDS = {
     unsafeSkipTransitionGuard: "modeled",
     rateLimit: "modeled",
     escapeHatch: "modeled",
+    tenantlessAnonymous: "opaque",
     perform: "opaque",
 };
 const QUERY_HANDLER_KEY_KINDS = {

package/dist/engine/feature-ast/extractors/hooks.js

@@ -1,3 +1,4 @@
+import { isEscapeHatchGrant } from "@cosmicdrift/kumiko-types/handlers";
 import { SyntaxKind } from "ts-morph";
 import { sourceLocationFromNode } from "../source-location.js";
 import { containsRawRefSentinel, fail, findFunctionLiteral, isPlainObject, ok, readDataLiteralNode, readNameLiteral, readNameOrRef, readNameOrRefOrList, readObjectPropertyInitializer, } from "./shared.js";
@@ -75,7 +76,12 @@ export function readOptionalEscapeHatch(value) {
         return undefined;
     if (typeof value["reason"] !== "string")
         return undefined;
-    return { reason: value["reason"] };
+    const grants = value["grants"];
+    if (grants === undefined)
+        return { reason: value["reason"] };
+    if (!Array.isArray(grants) || !grants.every(isEscapeHatchGrant))
+        return undefined;
+    return { reason: value["reason"], grants };
 }
 // Reads the `escapeHatch` sub-property node first, not via readDataLiteralNode
 // on the whole object: a sibling property like `handler` (a closure) isn't

package/dist/engine/feature-ast/pattern-change-schema.d.ts

@@ -197,6 +197,11 @@ export declare const PATTERN_SCHEMAS_BY_KIND: {
         }, z.core.$strict>]>>;
         escapeHatch: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
             reason: z.ZodString;
+            grants: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                globalWrites: "globalWrites";
+                systemIdentity: "systemIdentity";
+                unsafeRaw: "unsafeRaw";
+            }>>>;
         }, z.core.$strict>, z.ZodObject<{
             __raw: z.ZodString;
         }, z.core.$strict>]>>;
@@ -249,6 +254,11 @@ export declare const PATTERN_SCHEMAS_BY_KIND: {
         }, z.core.$strict>]>>;
         escapeHatch: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
             reason: z.ZodString;
+            grants: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                globalWrites: "globalWrites";
+                systemIdentity: "systemIdentity";
+                unsafeRaw: "unsafeRaw";
+            }>>>;
         }, z.core.$strict>, z.ZodObject<{
             __raw: z.ZodString;
         }, z.core.$strict>]>>;
@@ -290,6 +300,11 @@ export declare const PATTERN_SCHEMAS_BY_KIND: {
         }, z.core.$strict>]>>;
         escapeHatch: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
             reason: z.ZodString;
+            grants: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                globalWrites: "globalWrites";
+                systemIdentity: "systemIdentity";
+                unsafeRaw: "unsafeRaw";
+            }>>>;
         }, z.core.$strict>, z.ZodObject<{
             __raw: z.ZodString;
         }, z.core.$strict>]>>;
@@ -321,6 +336,11 @@ export declare const PATTERN_SCHEMAS_BY_KIND: {
         }>>;
         escapeHatch: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
             reason: z.ZodString;
+            grants: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                globalWrites: "globalWrites";
+                systemIdentity: "systemIdentity";
+                unsafeRaw: "unsafeRaw";
+            }>>>;
         }, z.core.$strict>, z.ZodObject<{
             __raw: z.ZodString;
         }, z.core.$strict>]>>;
@@ -689,6 +709,11 @@ export declare const patternSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }, z.core.$strict>]>>;
     escapeHatch: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
         reason: z.ZodString;
+        grants: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            globalWrites: "globalWrites";
+            systemIdentity: "systemIdentity";
+            unsafeRaw: "unsafeRaw";
+        }>>>;
     }, z.core.$strict>, z.ZodObject<{
         __raw: z.ZodString;
     }, z.core.$strict>]>>;
@@ -740,6 +765,11 @@ export declare const patternSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }, z.core.$strict>]>>;
     escapeHatch: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
         reason: z.ZodString;
+        grants: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            globalWrites: "globalWrites";
+            systemIdentity: "systemIdentity";
+            unsafeRaw: "unsafeRaw";
+        }>>>;
     }, z.core.$strict>, z.ZodObject<{
         __raw: z.ZodString;
     }, z.core.$strict>]>>;
@@ -780,6 +810,11 @@ export declare const patternSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }, z.core.$strict>]>>;
     escapeHatch: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
         reason: z.ZodString;
+        grants: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            globalWrites: "globalWrites";
+            systemIdentity: "systemIdentity";
+            unsafeRaw: "unsafeRaw";
+        }>>>;
     }, z.core.$strict>, z.ZodObject<{
         __raw: z.ZodString;
     }, z.core.$strict>]>>;
@@ -810,6 +845,11 @@ export declare const patternSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }>>;
     escapeHatch: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
         reason: z.ZodString;
+        grants: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            globalWrites: "globalWrites";
+            systemIdentity: "systemIdentity";
+            unsafeRaw: "unsafeRaw";
+        }>>>;
     }, z.core.$strict>, z.ZodObject<{
         __raw: z.ZodString;
     }, z.core.$strict>]>>;

package/dist/engine/feature-ast/pattern-change-schema.js

@@ -21,6 +21,7 @@
 // resolve this statically" markers) and, for EntityDefinition only,
 // additionally checked for field-type membership via the shared
 // `findUnknownEntityFieldTypes` helper (kept in sync with `extractEntity`).
+import { ESCAPE_HATCH_GRANTS } from "@cosmicdrift/kumiko-types/handlers";
 import * as z from "zod";
 import { LifecycleHookTypes } from "../constants.js";
 import { describeUnknownFieldType, findUnknownEntityFieldTypes } from "./entity-field-types.js";
@@ -131,6 +132,7 @@ const escapeHatchSchema = z
     reason: z.string().refine((s) => s.trim().length > 0, {
         message: "reason must be non-empty",
     }),
+    grants: z.array(z.enum(ESCAPE_HATCH_GRANTS)).min(1).optional(),
 })
     .strict();
 const rawRefSentinelSchema = z.object({ __raw: z.string() }).strict();

package/dist/engine/feature-config-events-jobs.js

@@ -1,4 +1,4 @@
-import { normalizeEventPiiSubject } from "@cosmicdrift/kumiko-types/handlers";
+import { escapeHatchGrantsProblem, normalizeEventPiiSubject, } from "@cosmicdrift/kumiko-types/handlers";
 import { ZodObject } from "zod";
 import { resolveName } from "./handler-helpers.js";
 import { splitNamedDefinition, unwrapArrayForm } from "./object-form.js";
@@ -124,6 +124,10 @@ export function buildConfigEventsJobsMethods(state, name) {
                 throw new Error(`[Feature ${name}] r.job("${jobName}") declares { escapeHatch: { reason: "" } } — ` +
                     "the reason must be a non-empty string explaining why this job needs unfiltered database access.");
             }
+            const jobGrantsProblem = jobOptions.escapeHatch && escapeHatchGrantsProblem(jobOptions.escapeHatch);
+            if (jobGrantsProblem) {
+                throw new Error(`[Feature ${name}] r.job("${jobName}") declares an invalid escapeHatch — ${jobGrantsProblem}`);
+            }
             // Resolve NameOrRef(s) in trigger.on. Multi-Trigger-Form: Array
             // wird zu Array von resolved strings, Single bleibt single string —
             // job-runner unterscheidet anhand Array.isArray.

package/dist/engine/feature-entity-handlers.js

@@ -106,6 +106,7 @@ export function buildEntityHandlerMethods(state, name) {
                     ...(def.unsafeSkipTransitionGuard && { unsafeSkipTransitionGuard: true }),
                     ...(def.rateLimit && { rateLimit: def.rateLimit }),
                     ...(def.escapeHatch && { escapeHatch: def.escapeHatch }),
+                    ...(def.tenantlessAnonymous && { tenantlessAnonymous: true }),
                     // Forward the pipeline-build closure so boot-validators and
                     // Designer/AI tooling can inspect the step list. Absent on
                     // free-form handlers — defineWriteHandler only sets `perform`