@cosmicdrift/kumiko-framework 0.337.1 → 0.338.0

package/dist/api/api-constants.d.ts

@@ -33,6 +33,7 @@ export declare const Routes: {
 };
 export declare const PUBLIC_API_PATHS: ReadonlySet<string>;
 export declare const NON_PUBLIC_API_PATHS: ReadonlySet<string>;
+export declare function isSessionRequiredApiPath(path: string): boolean;
 export declare const BODY_LIMIT_OPT_OUT_PATHS: ReadonlySet<string>;
 export declare const AUTH_RATE_LIMIT_EXEMPT_ROUTES: ReadonlyArray<{
     readonly method: string;

package/dist/api/api-constants.js

@@ -87,6 +87,15 @@ export const NON_PUBLIC_API_PATHS = new Set([
     `/api${Routes.files}`,
     `/api${Routes.schema}`,
 ]);
+// Paths that need a session but no tenant: without a token they answer 401
+// before any tenant resolution, so an unresolvable tenant can never turn
+// "not logged in" into a 400 tenant_required.
+const SESSION_REQUIRED_API_PREFIXES = [`/api${Routes.auth}/`];
+const SESSION_REQUIRED_API_EXACT_PATHS = new Set([`/api${Routes.schema}`]);
+export function isSessionRequiredApiPath(path) {
+    return (SESSION_REQUIRED_API_EXACT_PATHS.has(path) ||
+        SESSION_REQUIRED_API_PREFIXES.some((prefix) => path.startsWith(prefix)));
+}
 // Opt-out from the default request-body-size cap (registerBodyLimit applies
 // it to all of /api/* by construction — a new route needs no entry here to
 // be covered). Only routes with their own, deliberately different size

package/dist/api/auth-middleware.js

@@ -2,7 +2,7 @@ import { getCookie } from "hono/cookie";
 import { TENANT_TEARDOWN_STATUSES } from "../engine/active-membership.js";
 import { createAnonymousUser } from "../engine/system-user.js";
 import { parseTenantId } from "../engine/types/identifiers.js";
-import { TENANT_COOKIE_NAME, TENANT_HEADER_NAME } from "./api-constants.js";
+import { isSessionRequiredApiPath, TENANT_COOKIE_NAME, TENANT_HEADER_NAME, } from "./api-constants.js";
 import { isForeignCookieOrigin } from "./origin-middleware.js";
 const USER_KEY = "pipelineUser";
 const AUTH_TRANSPORT_KEY = "authTransport";
@@ -109,7 +109,7 @@ export function authMiddleware(jwt, options = {}) {
             // missing authentication, nicht missing tenant. Daher hier direkt
             // 401, ohne den anonymous-Tenant-Flow zu durchlaufen.
             if (anonymousAccess) {
-                if (c.req.path.startsWith("/api/auth/")) {
+                if (isSessionRequiredApiPath(c.req.path)) {
                     return middlewareReject(c, {
                         code: "missing_token",
                         status: 401,

package/dist/api/server.js

@@ -23,7 +23,7 @@ import { authEndpointRateLimit, createRateLimitResolver, globalIpRateLimit, } fr
 import { deriveSearchAdapterConfig } from "../search/derive-search-adapter-config.js";
 import { assertUnreachable, generateId } from "../utils/index.js";
 import { collectAnonymousLiveEntities } from "./anonymous-live-entities.js";
-import { NO_ROUTE_MATCH_HEADER_NAME, PUBLIC_API_PATHS, Routes } from "./api-constants.js";
+import { NO_ROUTE_MATCH_HEADER_NAME, NON_PUBLIC_API_PATHS, PUBLIC_API_PATHS, Routes, } from "./api-constants.js";
 import { authMiddleware, getAuthTokenExpiry, getUser, } from "./auth-middleware.js";
 import { assertSessionCallbacksPaired, createAuthRoutes, } from "./auth-routes.js";
 import { assertValidTrustedProxyHops, clientIpSourceFromHonoContext, createClientIpResolver, } from "./client-ip.js";
@@ -708,6 +708,16 @@ export function buildServer(options) {
                 throw new Error(`[kumiko] extraRoutes: entry:"signature" route "${route.method} ${route.path}" must not ` +
                     'use a wildcard under "/api/" — it would bypass the auth chain for every matching path.');
             }
+            // A `:param` segment is as broad as a wildcard, and the public matchers test
+            // the bare request path: "/:seg/write" and "/api/:hook" both match /api/write.
+            if (route.entry === ExtraRouteEntries.signature) {
+                const routePattern = honoPathToRegex(route.path);
+                const shadowedFrameworkPath = [...PUBLIC_API_PATHS, ...NON_PUBLIC_API_PATHS].find((path) => routePattern.test(path));
+                if (shadowedFrameworkPath !== undefined) {
+                    throw new Error(`[kumiko] extraRoutes: entry:"signature" route "${route.method} ${route.path}" must not ` +
+                        `match the framework path "${shadowedFrameworkPath}" — it would bypass the auth chain for it.`);
+                }
+            }
         }
         const dispatchSystemWrite = makeDispatchSystemWrite(dispatcher);
         const dispatchSystemQuery = makeDispatchSystemQuery(dispatcher);

package/dist/compliance/sub-processors.js

@@ -84,13 +84,22 @@ export const KUMIKO_SUB_PROCESSORS = [
     },
     {
         name: "Scaleway SAS",
-        purpose: "Offsite Backup Mirror (Object Storage); planned: platform key custody (Key Manager) and Transactional Email",
+        purpose: "Offsite Backup Mirror (Object Storage)",
         region: "EU (France)",
         dpa: "https://www.scaleway.com/en/contracts/",
         addedAt: "2026-09-18",
         appliesTo: ["all-tiers"],
         status: "active",
     },
+    {
+        name: "Scaleway SAS",
+        purpose: "Platform key custody (Key Manager) and Transactional Email Delivery",
+        region: "EU (France)",
+        dpa: "https://www.scaleway.com/en/contracts/",
+        addedAt: "2026-09-18",
+        appliesTo: ["all-tiers"],
+        status: "planned",
+    },
 ];
 /**
  * Filter helper — nur aktive Sub-Processors (kein status="planned").

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/tenant-db.js

@@ -61,7 +61,7 @@ export function unsafeRawForDeclaredStep(holder, reason) {
                 "createUncheckedSystemDb, or createSystemDbView — no declared unsafeRaw runner bound.",
         });
     }
-    return runner(reason);
+    return runner(reason, true);
 }
 const systemDbRebinders = new WeakMap();
 // Rebinds a hook's own escapeHatch onto ctx.systemDb, mirroring withUnsafeRawGrant: always
@@ -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(reason, forwardedDeclaredStep);
         }
         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) {
@@ -419,7 +426,7 @@ 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) {
+    function grantedUnsafeRawRunner(reason, forwardedDeclaredStep) {
         if (reason.trim().length === 0) {
             throw new Error("unsafeRaw requires a non-empty reason");
         }
@@ -433,14 +440,15 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
                     "the handler or hook 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 : (grants?.unsafeRaw?.reason ?? reason));
         return personalDataGate ? gatedRunner(db, personalDataGate) : db;
     }
     const tenantDb = {
         tenantId,
         mode,
         global: globalTable,
-        unsafeRaw: grantedUnsafeRawRunner,
+        unsafeRaw: (reason) => grantedUnsafeRawRunner(reason, false),
         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

@@ -22,3 +22,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

@@ -784,3 +784,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) {
@@ -184,7 +190,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/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/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-manifest.d.ts

@@ -7,6 +7,7 @@ export type ManifestConfigKey = {
     readonly default: string | number | boolean | null;
     readonly encrypted: boolean;
     readonly computed: boolean;
+    readonly validated: boolean;
     readonly options: readonly string[] | null;
     readonly bounds: {
         readonly min?: number;

package/dist/engine/feature-manifest.js

@@ -29,6 +29,7 @@ export function buildManifestFromRegistry(registry, options) {
                 default: def.default ?? null,
                 encrypted: isEncryptedAtRest(def),
                 computed: def.computed !== undefined,
+                validated: def.validate !== undefined,
                 options: def.options ?? null,
                 bounds: def.bounds ?? null,
                 pattern: def.pattern ?? null,

package/dist/engine/feature-ui-extensions.js

@@ -1,3 +1,4 @@
+import { escapeHatchGrantsProblem } from "@cosmicdrift/kumiko-types/handlers";
 import { WEBSOCKET_MAX_CONNECTIONS_PER_USER_LIMIT, WEBSOCKET_MAX_PAYLOAD_BYTES, WEBSOCKET_ROUTE_PATH_PREFIX, } from "@cosmicdrift/kumiko-types/websocket-route";
 import { bindHookEscapeHatchGrant } from "../pipeline/system-identity-switch.js";
 import { LifecycleHookTypes } from "./constants.js";
@@ -117,6 +118,10 @@ export function buildUiExtensionsMethods(state, name) {
                 throw new Error(`[Feature ${name}] r.hook("${type}", ...) declares { escapeHatch: { reason: "" } } — ` +
                     "the reason must be a non-empty string explaining why this hook switches identity to SYSTEM.");
             }
+            const hookGrantsProblem = options?.escapeHatch && escapeHatchGrantsProblem(options.escapeHatch);
+            if (hookGrantsProblem) {
+                throw new Error(`[Feature ${name}] r.hook("${type}", ...) declares an invalid escapeHatch — ${hookGrantsProblem}`);
+            }
             // Wrapped once for both branches below; validation hooks stay unwrapped (no context).
             const hookLabel = `${type} hook of feature "${name}"`;
             const wrapped = type === "validation"
@@ -211,6 +216,10 @@ export function buildUiExtensionsMethods(state, name) {
                     throw new Error(`[Feature ${name}] r.useExtension("${extensionName}", "${resolvedEntityName}", ...) declares an invalid { escapeHatch } — ` +
                         `must be { reason: "<non-empty string>" } explaining why this usage needs unfiltered db access.`);
                 }
+                const extGrantsProblem = escapeHatchGrantsProblem(escapeHatch);
+                if (extGrantsProblem) {
+                    throw new Error(`[Feature ${name}] r.useExtension("${extensionName}", "${resolvedEntityName}", ...) declares an invalid { escapeHatch } — ${extGrantsProblem}`);
+                }
             }
             state.extensionUsages.push({
                 extensionName,

package/dist/engine/index.d.ts

@@ -73,7 +73,7 @@ export { describeWorkflowStepError } from "./steps/describe-workflow-step-error.
 export { ANONYMOUS_ROLE, ANONYMOUS_USER_ID, createAnonymousUser, createSystemUser, SYSTEM_ROLE, SYSTEM_USER_ID, } from "./system-user.js";
 export { type EffectiveFeaturesResolver, findTierResolverUsage, isTierResolverPlugin, TENANT_TIER_RESOLVER_EXT, type TierResolverPlugin, type TrialGate, } from "./tier-resolver-extension.js";
 export { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers.js";
-export type { AccessRule, ActionFormScreenDefinition, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, BelongsToRelation, BigIntFieldDef, BooleanFieldDef, CamelToKebab, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, ConcurrencyMode, ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigCascade, ConfigCascadeLevel, ConfigDefinition, ConfigEditScreenDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigScope, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValue, ConfigValueSource, ConfigValueWithSource, ContentCollectionDefinition, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, CustomScreenDefinition, CustomScreenRoute, DashboardChartPanel, DashboardCustomPanel, DashboardFeedPanel, DashboardFilterDefinition, DashboardListPanel, DashboardPanelDefinition, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DateFieldDef, DecimalFieldDef, DeleteContext, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EntityDefinition, EntityEditScreenDefinition, EntityId, EntityListExpandableRow, EntityListScreenDefinition, EntityRef, EntityRelations, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, ExtensionOptionsArgs, ExtensionOptionsFor, FeatureDefinition, FeatureRegistrar, FieldAccess, FieldCondition, FieldDefinition, FieldFormatRegistry, FieldIconKey, FieldRenderer, FileFieldDef, FilesFieldDef, Findability, FormatSpec, FormWidth, HandlerContext, HasManyRelation, HookMap, ImageFieldDef, ImagesFieldDef, JobBackoff, JobBackoffStrategy, JobContext, JobDefinition, JobHandlerFn, JobTrigger, JobTriggerEvent, JsonbFieldDef, KumikoEntityTypeMap, KumikoEventTypeMap, KumikoExtensionOptionsMap, KumikoHandlerPayloadMap, KumikoHandlerResultMap, LifecycleHookType, ListColumnSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, LongTextFindability, ManyToManyRelation, MemberReader, MetricNavigate, MetricSpec, MspErrorMode, MspErrorPolicy, MultiSelectFieldDef, MultiStreamApplyFn, MultiStreamProjectionDefinition, NameOrRef, NavDefinition, NavIconKey, NotificationDataFn, NotificationDefinition, NotificationRecipientFn, NotificationTemplateFn, NotifyFactory, NotifyFn, NotifyOptions, NotifyPriority, NumberFieldDef, OnDeleteStrategy, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, PlatformComponent, PluralForms, PostDeleteHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, ProjectionDefinition, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, ProjectionTable, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitPer, RecordHeaderSpec, RecordHeaderSubtitlePart, ReferenceDataDef, Registry, RelationDefinition, ResolvedPiiFlags, RetentionDef, RoleAccessPersonalData, RoleAccessRule, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, SaveContext, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretKeyDefinition, SecretKeyHandle, SecretMintConfirmStep, SecretMintScreenDefinition, SecretNamespaceDefinition, SecretNamespaceHandle, SecretNamespaceOptions, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, SelectFieldDef, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, Subscribe, TargetRef, TenantId, TextFieldDef, ToolbarAction, TranslationEntry, TranslationKeys, TranslationsDef, TranslationValue, TreeAction, TreeActionDef, TreeActionsHandle, TreeChildrenSubscribe, TreeNode, TreeNodeState, UnitKey, UnsafeAppendEventFn, ValidationError, ValidationHookFn, WorkspaceDefinition, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "./types/index.js";
+export type { AccessRule, ActionFormScreenDefinition, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, BelongsToRelation, BigIntFieldDef, BooleanFieldDef, CamelToKebab, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, ConcurrencyMode, ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigCascade, ConfigCascadeLevel, ConfigDefinition, ConfigEditScreenDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigScope, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValidateContext, ConfigValidateFn, ConfigValue, ConfigValueSource, ConfigValueWithSource, ContentCollectionDefinition, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, CustomScreenDefinition, CustomScreenRoute, DashboardChartPanel, DashboardCustomPanel, DashboardFeedPanel, DashboardFilterDefinition, DashboardListPanel, DashboardPanelDefinition, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DateFieldDef, DecimalFieldDef, DeleteContext, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EntityDefinition, EntityEditScreenDefinition, EntityId, EntityListExpandableRow, EntityListScreenDefinition, EntityRef, EntityRelations, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, ExtensionOptionsArgs, ExtensionOptionsFor, FeatureDefinition, FeatureRegistrar, FieldAccess, FieldCondition, FieldDefinition, FieldFormatRegistry, FieldIconKey, FieldRenderer, FileFieldDef, FilesFieldDef, Findability, FormatSpec, FormWidth, HandlerContext, HasManyRelation, HookMap, ImageFieldDef, ImagesFieldDef, JobBackoff, JobBackoffStrategy, JobContext, JobDefinition, JobHandlerFn, JobTrigger, JobTriggerEvent, JsonbFieldDef, KumikoEntityTypeMap, KumikoEventTypeMap, KumikoExtensionOptionsMap, KumikoHandlerPayloadMap, KumikoHandlerResultMap, LifecycleHookType, ListColumnSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, LongTextFindability, ManyToManyRelation, MemberReader, MetricNavigate, MetricSpec, MspErrorMode, MspErrorPolicy, MultiSelectFieldDef, MultiStreamApplyFn, MultiStreamProjectionDefinition, NameOrRef, NavDefinition, NavIconKey, NotificationDataFn, NotificationDefinition, NotificationRecipientFn, NotificationTemplateFn, NotifyFactory, NotifyFn, NotifyOptions, NotifyPriority, NumberFieldDef, OnDeleteStrategy, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, PlatformComponent, PluralForms, PostDeleteHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, ProjectionDefinition, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, ProjectionTable, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitPer, RecordHeaderSpec, RecordHeaderSubtitlePart, ReferenceDataDef, Registry, RelationDefinition, ResolvedPiiFlags, RetentionDef, RoleAccessPersonalData, RoleAccessRule, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, SaveContext, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretKeyDefinition, SecretKeyHandle, SecretMintConfirmStep, SecretMintScreenDefinition, SecretNamespaceDefinition, SecretNamespaceHandle, SecretNamespaceOptions, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, SelectFieldDef, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, Subscribe, TargetRef, TenantId, TextFieldDef, ToolbarAction, TranslationEntry, TranslationKeys, TranslationsDef, TranslationValue, TreeAction, TreeActionDef, TreeActionsHandle, TreeChildrenSubscribe, TreeNode, TreeNodeState, UnitKey, UnsafeAppendEventFn, ValidationError, ValidationHookFn, WorkspaceDefinition, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "./types/index.js";
 export { DEFAULT_CURRENCIES, DEFAULT_LOCALES, HookPhases, isAgentVisibleScreen, isOpenToAllGranted, resolveAgentExposure, } from "./types/index.js";
 export type { AwaitedEventType, PipelineBuildCtx, PipelineCtx, PipelineDef, StepBuilder, StepDef, StepFailureStrategy, StepInstance, StepKind, StepNamespace, StepResolver, } from "./types/step.js";
 export { runValidation } from "./validation.js";

package/dist/engine/types/index.d.ts

@@ -1,5 +1,5 @@
 export { isAgentVisibleScreen, resolveAgentExposure, } from "@cosmicdrift/kumiko-types/agent-exposure";
-export type { ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigBounds, ConfigCascade, ConfigCascadeLevel, ConfigComputedContext, ConfigComputedFn, ConfigDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValue, ConfigValueSource, ConfigValueWithSource, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, ExtensionSelectorDef, ExtensionSelectorPanel, JobBackoff, JobBackoffStrategy, JobDefinition, JobHandlerFn, JobRunIn, JobTrigger, NotificationDataFn, NotificationDefinition, NotificationRecipientFn, NotificationTemplateFn, PluralForms, ReferenceDataDef, RegistrarExtensionDef, RegistrarExtensionHooks, RegistrarExtensionRegistration, RunIn, TranslationEntry, TranslationKeys, TranslationsDef, TranslationValue, UiExtensionDef, } from "@cosmicdrift/kumiko-types/config";
+export type { ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigBounds, ConfigCascade, ConfigCascadeLevel, ConfigComputedContext, ConfigComputedFn, ConfigDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValidateContext, ConfigValidateFn, ConfigValue, ConfigValueSource, ConfigValueWithSource, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, ExtensionSelectorDef, ExtensionSelectorPanel, JobBackoff, JobBackoffStrategy, JobDefinition, JobHandlerFn, JobRunIn, JobTrigger, NotificationDataFn, NotificationDefinition, NotificationRecipientFn, NotificationTemplateFn, PluralForms, ReferenceDataDef, RegistrarExtensionDef, RegistrarExtensionHooks, RegistrarExtensionRegistration, RunIn, TranslationEntry, TranslationKeys, TranslationsDef, TranslationValue, UiExtensionDef, } from "@cosmicdrift/kumiko-types/config";
 export type { QueryHandlerDefinition, StreamHandlerDefinition, WriteHandlerDefinition, WriteHandlerInput, } from "@cosmicdrift/kumiko-types/define-handler";
 export type { EntityCrudRegistrar, EntityCrudVerb, EntityHandlerOptions, EntityQueryHandlerOptions, EntityWriteHandlerOptions, RegisterEntityCrudOptions, } from "@cosmicdrift/kumiko-types/entity-handlers";
 export type { KumikoEntityTypeMap, KumikoEventTypeMap, KumikoHandlerPayloadMap, KumikoHandlerResultMap, } from "@cosmicdrift/kumiko-types/event-type-map";

package/dist/jobs/job-runner.js

@@ -1,3 +1,4 @@
+import { escapeHatchFor } from "@cosmicdrift/kumiko-types/handlers";
 import { Queue, UnrecoverableError, Worker } from "bullmq";
 import { Redis } from "ioredis";
 import { requestContext } from "../api/request-context.js";
@@ -703,7 +704,7 @@ export function createJobRunner(options) {
             : undefined;
         const jobDb = configDb
             ? createTenantDb(configDb, tenantId, "tenant", context.tracer, context.meter, undefined, {
-                unsafeRaw: jobDef.escapeHatch,
+                unsafeRaw: escapeHatchFor(jobDef.escapeHatch, "unsafeRaw"),
                 report: reportEscapeHatch,
                 ...(jobPersonalDataGate && { personalDataGate: jobPersonalDataGate }),
             })

package/dist/pipeline/dispatch-shared.js

@@ -1,9 +1,11 @@
+import { escapeHatchFor } from "@cosmicdrift/kumiko-types/handlers";
 import { requestContext, runWithOrigin } from "../api/request-context.js";
 import { runInSavepoint, selectMany } from "../db/query.js";
 import { createTenantDb, createUncheckedSystemDb, hasTenantColumn, } from "../db/tenant-db.js";
 import { createDerivativesContext } from "../derivatives/derivatives-context.js";
+import { createSystemUser } from "../engine/system-user.js";
 import { isRateLimitDisabled, resolveAgentExposure } from "../engine/types/index.js";
-import { FeatureDisabledError, InternalError, memberResolutionReadOnlyDenied, VersionConflictError, } from "../errors/index.js";
+import { AccessDeniedError, FeatureDisabledError, InternalError, memberResolutionReadOnlyDenied, VersionConflictError, } from "../errors/index.js";
 import { archiveStream as archiveStreamHelper, isStreamArchived, restoreStream as restoreStreamHelper, } from "../event-store/archive.js";
 import { IdempotentAppendConflictError as EventStoreIdempotentAppendConflictError, VersionConflictError as EventStoreVersionConflictError, } from "../event-store/errors.js";
 import { getStreamVersion, loadAggregate, loadAggregateAsOf, } from "../event-store/event-store.js";
@@ -148,7 +150,8 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
     const handlerEscapeHatch = writeEscapeHatch ??
         registry.getQueryHandler(type)?.escapeHatch ??
         registry.getStreamHandler(type)?.escapeHatch;
-    const hasIdentitySwitchGrant = isSystem || handlerEscapeHatch !== undefined;
+    const identitySwitchEscapeHatch = escapeHatchFor(handlerEscapeHatch, "systemIdentity");
+    const hasIdentitySwitchGrant = isSystem || identitySwitchEscapeHatch !== undefined;
     const featureName = registry.getHandlerFeature(type);
     const reportEscapeHatch = createEscapeHatchReporter({
         handler: type,
@@ -158,11 +161,11 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
         log: context.log,
         window: ctx.escapeHatchReportWindow,
     });
-    const identitySwitchGrantReason = handlerEscapeHatch?.reason ??
+    const identitySwitchGrantReason = identitySwitchEscapeHatch?.reason ??
         (isSystem ? `r.systemScope() feature "${featureName ?? "unknown"}"` : undefined);
     const buildTenantScopedDb = (source, signal) => createTenantDb(source, user.tenantId, isSystem ? "system" : "tenant", context.tracer, context.meter, signal, {
-        globalWrites: writeEscapeHatch,
-        unsafeRaw: handlerEscapeHatch,
+        globalWrites: escapeHatchFor(writeEscapeHatch, "globalWrites"),
+        unsafeRaw: escapeHatchFor(handlerEscapeHatch, "unsafeRaw"),
         report: reportEscapeHatch,
         memberReadOnly: isMemberResolutionPrincipal(user),
         personalDataGate: buildPersonalDataGate(registry, origin),
@@ -212,6 +215,29 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
             secrets: context.secrets,
         })
         : undefined;
+    // Cross-tenant accessor for SystemAdmin/system callers. The
+    // identity is the target tenant's system user so the caller's own user-scope
+    // values never resolve into another tenant's config; the db is tenant-mode
+    // scoped to the target.
+    const configFactory = context._configAccessorFactory;
+    const configFor = configFactory && dbSource
+        ? (targetTenantId) => {
+            if (targetTenantId === user.tenantId && config)
+                return config;
+            if (!isSystemIdentity(user) && !user.roles.includes("SystemAdmin")) {
+                throw new AccessDeniedError({
+                    message: "ctx.configFor(otherTenant) requires the system role or SystemAdmin",
+                    details: { reason: "config_for_requires_system_admin" },
+                });
+            }
+            const targetSystemUser = createSystemUser(targetTenantId);
+            return configFactory({
+                user: { id: targetSystemUser.id, tenantId: targetTenantId },
+                db: createTenantDb(dbSource, targetTenantId, "tenant", context.tracer, context.meter),
+                secrets: context.secrets,
+            });
+        }
+        : undefined;
     // ctx.files resolved per-tenant through file-foundation (lazy — the
     // provider is only resolved when a handle actually does I/O). Boot wires
     // _fileProviderResolver when a file-provider plugin is mounted; falls back
@@ -584,6 +610,7 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
         log,
         notify,
         ...(config && { config }),
+        ...(configFor && { configFor }),
         ...(files && { files }),
         ...(derivatives && { derivatives }),
         // preSave hooks need `changes`/`previous`/`isNew`, which only exist once

package/dist/pipeline/system-identity-switch.js

@@ -1,3 +1,4 @@
+import { escapeHatchFor } from "@cosmicdrift/kumiko-types/handlers";
 import { withSystemDbUnsafeRawGrant, withUnsafeRawGrant, } from "../db/tenant-db.js";
 import { SYSTEM_ROLE, SYSTEM_USER_ID } from "../engine/system-user.js";
 import { AccessDeniedError, FrameworkReasons, InternalError } from "../errors/index.js";
@@ -212,6 +213,8 @@ export function withHookEscapeHatchGrant(context, callerLabel, escapeHatch) {
     const ctxDb = readDbLikeValue(context, "db");
     const ctxDbOutsideTransaction = readDbLikeValue(context, "dbOutsideTransaction");
     const ctxSystemDb = readDbLikeValue(context, "systemDb");
+    const identityHatch = escapeHatchFor(escapeHatch, "systemIdentity");
+    const rawHatch = escapeHatchFor(escapeHatch, "unsafeRaw");
     if (!ctxQueryAs &&
         !ctxWriteAs &&
         !ctxResolveActiveMembership &&
@@ -224,21 +227,21 @@ export function withHookEscapeHatchGrant(context, callerLabel, escapeHatch) {
     }
     return {
         ...context,
-        ...gatedIdentitySwitchFields(callerLabel, escapeHatch, ctxQueryAs, ctxWriteAs),
+        ...gatedIdentitySwitchFields(callerLabel, identityHatch, ctxQueryAs, ctxWriteAs),
         ...(ctxResolveActiveMembership &&
-            escapeHatch === undefined && {
+            identityHatch === undefined && {
             resolveActiveMembership: deniedResolveActiveMembership(callerLabel),
         }),
-        ...gatedMemberReaderField(callerLabel, escapeHatch, ctxQueryAsMember),
-        ...gatedProjectionReaderField(callerLabel, escapeHatch, ctxQueryProjection),
+        ...gatedMemberReaderField(callerLabel, identityHatch, ctxQueryAsMember),
+        ...gatedProjectionReaderField(callerLabel, identityHatch, ctxQueryProjection),
         // @cast-boundary engine-bridge — withUnsafeRawGrant passes non-TenantDb values (e.g. a guard Proxy) through unchanged.
-        ...(ctxDb && { db: withUnsafeRawGrant(ctxDb, escapeHatch) }),
+        ...(ctxDb && { db: withUnsafeRawGrant(ctxDb, rawHatch) }),
         ...(ctxDbOutsideTransaction && {
-            dbOutsideTransaction: withUnsafeRawGrant(ctxDbOutsideTransaction, escapeHatch),
+            dbOutsideTransaction: withUnsafeRawGrant(ctxDbOutsideTransaction, rawHatch),
         }),
         // @cast-boundary engine-bridge — withSystemDbUnsafeRawGrant passes non-UncheckedSystemDb values through unchanged.
         ...(ctxSystemDb && {
-            systemDb: withSystemDbUnsafeRawGrant(ctxSystemDb, escapeHatch, callerLabel),
+            systemDb: withSystemDbUnsafeRawGrant(ctxSystemDb, rawHatch, callerLabel),
         }),
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.337.1",
+  "version": "0.338.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -206,8 +206,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.337.1",
-    "@cosmicdrift/kumiko-types": "0.337.1",
+    "@cosmicdrift/kumiko-http": "0.338.0",
+    "@cosmicdrift/kumiko-types": "0.338.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -223,7 +223,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.337.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.338.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,65 @@
 [
+  {
+    "version": "0.338.0",
+    "type": "improvement",
+    "title": "ctx.configFor(tenantId) resolves config for another tenant",
+    "detail": "Query and write handler contexts get `configFor(tenantId)` next to `config`, present when the config feature wired its accessor factory. The accessor runs as the target tenant's system user on a db scoped to that tenant, so the caller's user-scope values never leak into the result. Calls for another tenant throw `AccessDeniedError` unless the caller is the system identity or has the `SystemAdmin` role; the caller's own tenant needs no privilege and returns the same accessor as `ctx.config`.",
+    "migration": "No code change needed. Handlers that compute values for a tenant other than the caller's (limits, quotas, billing previews) call `ctx.configFor(tenantId)` instead of passing `ctx.config`."
+  },
+  {
+    "version": "0.338.0",
+    "type": "improvement",
+    "title": "escapeHatch grants split the SYSTEM identity switch from raw access",
+    "detail": "escapeHatch: new optional `grants` (`systemIdentity`, `globalWrites`, `unsafeRaw`) narrows what a declaration unlocks. Without `grants` the declaration keeps unlocking all three. An empty or unknown `grants` list is a boot error. Bundled handlers that only needed the raw runner now declare `grants: [\"unsafeRaw\"]`, so they no longer gain the SYSTEM identity switch.",
+    "migration": "No action needed: `grants` is additive and an escapeHatch without it behaves as before.\nDeclare `grants: [\"unsafeRaw\"]` on handlers that only call ctx.db.unsafeRaw to drop the SYSTEM identity switch."
+  },
+  {
+    "version": "0.338.0",
+    "type": "improvement",
+    "title": "boot warning for file and image fields without a personal annotation",
+    "detail": "Boot validation warns for every `file`, `image`, `files` and `images` field without a `personal` annotation. A forget with strategy `delete` keeps the binary of such a field and only severs the uploader link, so the stance has to be declared.",
+    "migration": "Mark fields that hold personal data with `personal: \"self\"` or `personal: { of: \"<ownerField>\" }`, and business data with `personal: false, reason: \"is_business_data\"`. Unannotated fields keep their binary on forget."
+  },
+  {
+    "version": "0.338.0",
+    "type": "fix",
+    "title": "reference label search applies target read access on the plaintext path",
+    "detail": "Searching a list by a reference field's label now respects the target entity's row-level `access.read` and the label field's own `access.read` on the plaintext (ILIKE) path. Before, a viewer who could not read the target row or its label could probe names through the match results."
+  },
+  {
+    "version": "0.338.0",
+    "type": "fix",
+    "title": "/api/schema answers 401 instead of 400 tenant_required after logout",
+    "detail": "With `anonymousAccess` and an authoritative tenant resolver, a request without a token to `/api/schema` ran through tenant resolution and failed with 400 `tenant_required`. Paths that need a session but no tenant (`/api/auth/*` and `/api/schema`) are now listed in `isSessionRequiredApiPath` and answer 401 `missing_token` before any tenant lookup.",
+    "migration": "No code change needed."
+  },
+  {
+    "version": "0.338.0",
+    "type": "breaking",
+    "title": "searchable text fields must not declare a restricted access.read",
+    "detail": "Boot validation rejects a text field that is `searchable` (or `find: \"fuzzy\"`) and also has a restricted `access.read`. The search index is not filtered per role, so search matches leaked the value to roles that cannot read the field.",
+    "migration": "Remove `searchable` / `find: \"fuzzy\"` from the field, or remove the read restriction. Write-only `access.write` restrictions are unaffected."
+  },
+  {
+    "version": "0.338.0",
+    "type": "breaking",
+    "title": "signature routes with a :param segment or wildcard must not match framework paths",
+    "detail": "Boot validation rejects `entry: \"signature\"` extra routes whose pattern, including `:param` segments, matches a framework path such as `/api/write`. Such a route skipped the JWT, origin and CSRF guards for that path.",
+    "migration": "Give the route a static prefix, for example `/api/webhooks/:provider` instead of `/api/:provider` or `/:provider/write`."
+  },
+  {
+    "version": "0.338.0",
+    "type": "fix",
+    "title": "planned Scaleway purposes listed as planned sub-processor entry",
+    "detail": "The sub-processor list now carries the planned Scaleway purposes (key custody and transactional email) as their own `status: \"planned\"` entry. The active Scaleway entry only names the backup mirror, so the public `planned` section and change notifications see the upcoming processing."
+  },
+  {
+    "version": "0.338.0",
+    "type": "improvement",
+    "title": "unsafeRaw audit events carry the declared escapeHatch reason",
+    "detail": "`ctx.db.unsafeRaw(reason)` and `ctx.systemDb.unsafeRaw(reason)` now write the reason declared on the handler or hook `escapeHatch` into the escape-hatch audit event, not the string passed at the call. A call-site string can no longer put arbitrary text into the audit trail.",
+    "migration": "No action needed: calls that pass the same reason as the declaration audit unchanged. Calls with a different string now audit the declared reason."
+  },
   {
     "version": "0.337.1",
     "type": "improvement",