@cosmicdrift/kumiko-framework 0.352.0 → 0.354.0

package/dist/api/index.d.ts

@@ -19,7 +19,7 @@ export type { PostAuthLandingArgs, PostAuthLandingFlow, PostAuthLandingResolver,
 export { isSafeLandingPath } from "./post-auth-landing.js";
 export type { RedisSseBroker, RedisSseBrokerOptions } from "./redis-sse-broker.js";
 export { createDefaultSseBroker, createRedisSseBroker, isRedisSseBroker, } from "./redis-sse-broker.js";
-export { type RequestContextData, requestContext, runAsDirectCallEntry, } from "./request-context.js";
+export { type RequestContextData, readonlyRequestContext as requestContext, } from "./request-context.js";
 export { buildRequestContextDataFromRequest, requestIdMiddleware, } from "./request-id-middleware.js";
 export type { MetricsRouteOptions } from "./route-registrars.js";
 export { createMetricsApp, DEFAULT_MAX_REQUEST_BYTES, isPrometheusMeter, } from "./route-registrars.js";

package/dist/api/index.js

@@ -10,7 +10,7 @@ export { createJwtHelper, loadJwtSecretOrKeyring } from "./jwt.js";
 export { patAllows, qnMatches } from "./pat-scope.js";
 export { isSafeLandingPath } from "./post-auth-landing.js";
 export { createDefaultSseBroker, createRedisSseBroker, isRedisSseBroker, } from "./redis-sse-broker.js";
-export { requestContext, runAsDirectCallEntry, } from "./request-context.js";
+export { readonlyRequestContext as requestContext, } from "./request-context.js";
 export { buildRequestContextDataFromRequest, requestIdMiddleware, } from "./request-id-middleware.js";
 export { createMetricsApp, DEFAULT_MAX_REQUEST_BYTES, isPrometheusMeter, } from "./route-registrars.js";
 export { createApiRoutes } from "./routes.js";

package/dist/api/pii-leak-guard.js

@@ -13,6 +13,9 @@ const CIPHERTEXT_REDACT_RE = new RegExp(CIPHERTEXT_RE.source, "g");
 // red; prod redacts + logs instead of shipping the blob. Scans unconditionally:
 // legacy ciphertext rows can outlive a subject KMS that later became
 // unconfigured, and the marker check itself needs no KMS access to run.
+// Buffers every JSON body (no streaming, roughly double peak memory for large
+// exports) on purpose: a size threshold or opt-out would be a leak bypass for
+// exactly the large responses most likely to carry raw rows.
 export function piiCiphertextResponseGuard() {
     return async (c, next) => {
         await next();

package/dist/api/redis-sse-broker.d.ts

@@ -3,6 +3,7 @@ import { type SseBroker } from "./sse-broker.js";
 export type RedisSseBrokerOptions = {
     readonly redisUrl: string;
     readonly clientOptions?: RedisClientOptions;
+    readonly channelPrefix?: string;
 };
 export type RedisSseBroker = SseBroker & {
     readonly kind: "redis";

package/dist/api/redis-sse-broker.js

@@ -1,4 +1,4 @@
-import { redisClientOptionsFromEnv } from "../redis/client.js";
+import { redisChannelPrefixFromEnv, redisClientOptionsFromEnv, } from "../redis/client.js";
 import { createRedisPubSubSignal } from "../redis/pubsub-signal.js";
 import { createSseBroker, readNonEmptyStringArray, } from "./sse-broker.js";
 // Channel namespace for cross-replica fanout (fw#2625). Every pod publishes
@@ -8,7 +8,7 @@ import { createSseBroker, readNonEmptyStringArray, } from "./sse-broker.js";
 // cursor stays the mechanism for "read every event exactly once".
 const CHANNEL_PREFIX = "kumiko:sse:ch:";
 const INVALIDATION_PREFIX = "kumiko:sse:inval:";
-const PSUBSCRIBE_PATTERN = "kumiko:sse:*";
+const PSUBSCRIBE_SUFFIX = "kumiko:sse:*";
 // Narrows on the `kind` discriminant, not on `close`: an app-owned SseBroker
 // may have its own close() and must not be mistaken for the Redis one.
 export function isRedisSseBroker(broker) {
@@ -26,7 +26,11 @@ export function isRedisSseBroker(broker) {
 export function createDefaultSseBroker(env = process.env) {
     const redisUrl = env["REDIS_URL"];
     const ownedRedisSseBroker = redisUrl
-        ? createRedisSseBroker({ redisUrl, clientOptions: redisClientOptionsFromEnv(env) })
+        ? createRedisSseBroker({
+            redisUrl,
+            clientOptions: redisClientOptionsFromEnv(env),
+            channelPrefix: redisChannelPrefixFromEnv(env),
+        })
         : undefined;
     return { sseBroker: ownedRedisSseBroker ?? createSseBroker(), ownedRedisSseBroker };
 }
@@ -92,26 +96,28 @@ function encodeInvalidationScope(scope) {
 // the request.
 export function createRedisSseBroker(opts) {
     const inner = createSseBroker();
+    const channelPrefix = `${opts.channelPrefix ?? ""}${CHANNEL_PREFIX}`;
+    const invalidationPrefix = `${opts.channelPrefix ?? ""}${INVALIDATION_PREFIX}`;
     const signal = createRedisPubSubSignal({
         redisUrl: opts.redisUrl,
-        channelPattern: PSUBSCRIBE_PATTERN,
+        channelPattern: `${opts.channelPrefix ?? ""}${PSUBSCRIBE_SUFFIX}`,
         label: "sse-broker",
         ...(opts.clientOptions ? { clientOptions: opts.clientOptions } : {}),
     });
     signal.onMessage((channel, payload) => {
-        if (channel.startsWith(CHANNEL_PREFIX)) {
+        if (channel.startsWith(channelPrefix)) {
             if (!isSseEvent(payload)) {
                 console.error(`[kumiko:sse-broker] dropping malformed event on "${channel}"`);
                 // skip: malformed payload already logged above, nothing to deliver
                 return;
             }
-            inner.pushToChannel(channel.slice(CHANNEL_PREFIX.length), payload);
+            inner.pushToChannel(channel.slice(channelPrefix.length), payload);
             // skip: channel already routed to the SSE-event branch above, the
             // invalidation branch below is mutually exclusive with this one
             return;
         }
-        if (channel.startsWith(INVALIDATION_PREFIX)) {
-            inner.publishAccessInvalidation(channel.slice(INVALIDATION_PREFIX.length), parseInvalidationScope(payload));
+        if (channel.startsWith(invalidationPrefix)) {
+            inner.publishAccessInvalidation(channel.slice(invalidationPrefix.length), parseInvalidationScope(payload));
         }
     });
     return {
@@ -122,14 +128,14 @@ export function createRedisSseBroker(opts) {
         getTotalClientCount: inner.getTotalClientCount,
         subscribeAccessInvalidation: inner.subscribeAccessInvalidation,
         pushToChannel(channel, event) {
-            signal.publish(`${CHANNEL_PREFIX}${channel}`, event);
+            return signal.publishConfirmed(`${channelPrefix}${channel}`, event);
         },
         // fw#1601: this is the security-critical call — a revoked session's
         // stream must close on every replica, not just the one that observed
         // the revocation event. Publishing (rather than calling inner directly,
         // like the in-memory broker does) is what makes that true here.
         publishAccessInvalidation(userId, scope) {
-            signal.publish(`${INVALIDATION_PREFIX}${userId}`, encodeInvalidationScope(scope));
+            return signal.publishConfirmed(`${invalidationPrefix}${userId}`, encodeInvalidationScope(scope));
         },
         close: signal.close,
     };

package/dist/api/request-context.d.ts

@@ -25,6 +25,7 @@ export declare const requestContext: {
     get(): RequestContextData | undefined;
     generateId(): string;
 };
+export declare const readonlyRequestContext: Pick<typeof requestContext, "get">;
 export declare function runWithOrigin<T>(origin: {
     readonly feature?: string;
     readonly handler?: string;

package/dist/api/request-context.js

@@ -13,6 +13,11 @@ export const requestContext = {
         return generateId();
     },
 };
+// Public view: `run` would let a caller replace the request scope (entryHandler,
+// writeOrigin), so only the read side is exposed through the /api barrel.
+export const readonlyRequestContext = {
+    get: requestContext.get,
+};
 // Enter a scope that attributes every event written inside it. Keeps the
 // surrounding request's ids so correlation survives, and mints fresh ones
 // when there is no surrounding request (job-runner, event-dispatcher) —

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

@@ -1,10 +1,11 @@
-import { Hono } from "hono";
+import { Hono, type MiddlewareHandler } from "hono";
 import type { DbConnection } from "../db/connection.js";
 import type { Lifecycle } from "../lifecycle/index.js";
 import type { Meter, PrometheusMeter } from "../observability/index.js";
 import type { EventConsumer } from "../pipeline/event-dispatcher.js";
 export declare const DEFAULT_MAX_REQUEST_BYTES = 1048576;
 export declare function registerBodyLimit(app: Hono, maxBytes: number): void;
+export declare function bodyLimitForRoutePath(path: string, maxBytes: number): readonly MiddlewareHandler[];
 export type MetricsRouteOptions = {
     readonly token?: string;
     readonly path?: string;

package/dist/api/route-registrars.js

@@ -31,6 +31,14 @@ export function registerBodyLimit(app, maxBytes) {
         return limit(c, next);
     });
 }
+// registerBodyLimit only covers /api/*; signature routes outside it (webhook
+// receivers, OAuth callbacks) read the raw body before verify() runs and so
+// need the same cap on their own handler chain.
+export function bodyLimitForRoutePath(path, maxBytes) {
+    if (maxBytes <= 0 || path === "/api" || path.startsWith("/api/"))
+        return [];
+    return [bodyLimit({ maxSize: maxBytes })];
+}
 // Timing-safe string compare — equal-length strings compare every byte
 // regardless of where they diverge; different lengths return false without
 // iterating. Prevents side-channel leaks on the Bearer-token check.

package/dist/api/routes.js

@@ -5,7 +5,7 @@ import { AccessDeniedError, reraiseAsKumikoError, serializeError, toKumikoError,
 import { createFallbackLogger } from "../logging/index.js";
 import { stringifyJson } from "../utils/safe-json.js";
 import { Routes } from "./api-constants.js";
-import { getUser } from "./auth-middleware.js";
+import { getAuthTokenExpiry, getUser } from "./auth-middleware.js";
 import { patAllows } from "./pat-scope.js";
 import { requestContext } from "./request-context.js";
 import { SSE_HEARTBEAT_INTERVAL_MS } from "./sse-route.js";
@@ -133,7 +133,9 @@ export function createApiRoutes(dispatcher, options = {}) {
         try {
             assertPayloadDepthAllowed(body.payload);
             assertPatAllowed(user, body.type);
-            generator = dispatcher.stream(body.type, body.payload, user);
+            generator = dispatcher.stream(body.type, body.payload, user, {
+                tokenExpiresAtSec: getAuthTokenExpiry(c),
+            });
         }
         catch (e) {
             return queryErrorResponse(c, toKumiko(e), body.type);

package/dist/api/server.js

@@ -40,7 +40,7 @@ import { piiCiphertextResponseGuard } from "./pii-leak-guard.js";
 import { createDefaultSseBroker } from "./redis-sse-broker.js";
 import { requestContext } from "./request-context.js";
 import { buildRequestContextData, requestIdMiddleware } from "./request-id-middleware.js";
-import { DEFAULT_MAX_REQUEST_BYTES, registerBodyLimit, registerHealthRoutes, registerMetricsRoute, registerVersionRoute, } from "./route-registrars.js";
+import { bodyLimitForRoutePath, DEFAULT_MAX_REQUEST_BYTES, registerBodyLimit, registerHealthRoutes, registerMetricsRoute, registerVersionRoute, } from "./route-registrars.js";
 import { createApiRoutes, handleUncaughtRouteError } from "./routes.js";
 import { createSseRoute } from "./sse-route.js";
 import { buildWebSocketSessionRevalidator, createWebSocketConnectionLimiter, hasWebSocketUpgradeServer, isWebSocketUpgradeRequest, WEBSOCKET_DEFAULT_MAX_CONNECTIONS_PER_USER, WEBSOCKET_DEFAULT_MAX_MESSAGE_BYTES, } from "./websocket-route.js";
@@ -130,6 +130,9 @@ export function buildServer(options) {
         const defaults = createDefaultSseBroker();
         sseBroker = defaults.sseBroker;
         ownedRedisSseBroker = defaults.ownedRedisSseBroker;
+        if (!ownedRedisSseBroker) {
+            console.warn("[kumiko:boot] REDIS_URL is not set: cross-replica fanout disabled. SSE, access-invalidation and toggle-sync reach only the cursor-owning process, so with more than one replica clients on the other replicas miss events and revoked sessions stay open there.");
+        }
     }
     // Same decision as the SSE broker: an explicit dispatcherOptions value
     // (incl. null = opt out) wins, otherwise REDIS_URL turns on cross-replica
@@ -215,6 +218,21 @@ export function buildServer(options) {
         : (options.jwtSecret.keys[options.jwtSecret.signKid] ?? ""));
     const rateLimitResolver = options.context.rateLimit ??
         (wrappedRedis && wantsResolver ? createRateLimitResolver({ redis: wrappedRedis }) : undefined);
+    if (!rateLimitResolver) {
+        // The systemScope default limit only exists once a resolver does, and an app that
+        // declared no explicit rateLimit anywhere never gets one auto-wired (wantsL3 stays
+        // false) — so its cross-tenant handlers are silently unlimited.
+        const unlimitedSystemScopeFeatures = [...options.registry.features.values()]
+            .filter((feature) => feature.systemScope &&
+            Object.keys(feature.writeHandlers).length + Object.keys(feature.queryHandlers).length > 0)
+            .map((feature) => feature.name);
+        if (unlimitedSystemScopeFeatures.length > 0) {
+            console.warn(`[kumiko:boot] r.systemScope() features have handlers but no RateLimitResolver is configured, ` +
+                `so their default rate limit is not enforced: ${unlimitedSystemScopeFeatures.join(", ")}. ` +
+                "Wire a Redis client on context.redis and declare rateLimit on at least one handler (or pass " +
+                "context.rateLimit) to enable the resolver.");
+        }
+    }
     const contextWithObservability = {
         ...contextWithFiles,
         ...(wrappedRedis ? { redis: wrappedRedis } : {}),
@@ -342,7 +360,7 @@ export function buildServer(options) {
             // cross-feature ctx.appendEvent calls at emit-site.
             const mspOwner = msp.name.split(":")[0];
             const mspFiles = fileProviderResolver
-                ? createFileContext(() => fileProviderResolver(event.tenantId))
+                ? createFileContext(() => fileProviderResolver(event.tenantId), event.tenantId)
                 : undefined;
             const applyCtx = createMultiStreamApplyContext({
                 registry: options.registry,
@@ -438,17 +456,19 @@ export function buildServer(options) {
     // resolver is the auto-wired one (or `context.rateLimit` if set);
     // boot-fails loudly when the caller asked for middleware without a
     // working Redis to back it.
+    let globalRateLimitGuard;
     if (wantsL1L2) {
         if (!rateLimitResolver) {
             throw new Error("rateLimit middleware requested but no resolver available — pass `context.redis` " +
                 "or `context.rateLimit` so the resolver can be built.");
         }
         if (options.rateLimit?.global) {
-            app.use("/api/*", globalIpRateLimit({
+            globalRateLimitGuard = globalIpRateLimit({
                 ...options.rateLimit.global,
                 resolver: rateLimitResolver,
                 clientIpResolver,
-            }));
+            });
+            app.use("/api/*", globalRateLimitGuard);
         }
         if (options.rateLimit?.auth) {
             const { path: l2Path = "/api/auth/*", ...l2Opts } = options.rateLimit.auth;
@@ -564,7 +584,12 @@ export function buildServer(options) {
         return csrfGuard(c, next);
     });
     // No PAT rate-limit here: patRouteGuardMiddleware rejects every PAT on httpRoutes before it could count.
+    // httpRoutes sit outside /api/*, so the pre-auth /api/* middlewares do not run for them: the
+    // global IP limit (an unauthenticated flood must not reach JWT verify / session checks) and the
+    // PII ciphertext tripwire are re-attached here. requestId, body limit and observability are not.
     const sessionOnlyHttpRouteGuards = [
+        ...(globalRateLimitGuard ? [globalRateLimitGuard] : []),
+        piiCiphertextResponseGuard(),
         sessionOnlyGuard,
         patRouteGuardMiddleware,
         ...(originGuard ? [originGuard] : []),
@@ -782,7 +807,9 @@ export function buildServer(options) {
                 dispatchSystemQuery,
                 clientIpResolver,
             });
-            mountHonoRoute(app, route.method, route.path, honoHandler);
+            mountHonoRoute(app, route.method, route.path, honoHandler, route.entry === ExtraRouteEntries.signature
+                ? bodyLimitForRoutePath(route.path, options.maxRequestBytes ?? DEFAULT_MAX_REQUEST_BYTES)
+                : []);
         }
     }
     // /version-Default registriert NACH feature-routes — Hono "first match
@@ -927,6 +954,7 @@ function unauthenticatedResponse(c) {
     }, 401);
 }
 const webSocketLog = createFallbackLogger("websocket");
+const extraRouteLog = createFallbackLogger("extra-route");
 function webSocketErrorResponse(c, status, code, message) {
     return c.json({ error: { code, httpStatus: status, message } }, status);
 }
@@ -1069,10 +1097,15 @@ function buildExtraRouteHonoHandler(route, shared) {
                         }
                         return c.json(e.body, e.status);
                     }
+                    // The body goes to unauthenticated callers; infra errors thrown by
+                    // verify() (secrets, DB) must not leak, so the detail stays in the log.
+                    extraRouteLog.error(`signature verify() threw on ${c.req.path}`, {
+                        error: e instanceof Error ? e.message : String(e),
+                    });
                     return c.json({
                         error: {
                             code: "extra_route_signature_invalid",
-                            message: e instanceof Error ? e.message : String(e),
+                            message: "signature verification failed",
                         },
                     }, 401);
                 }

package/dist/api/sse-broker.d.ts

@@ -29,11 +29,15 @@ export declare function accessInvalidationCredentialFor(user: Pick<SessionUser,
 export type SseBroker = {
     addClient(channel: string, send: (event: SseEvent) => void, close: () => void): string;
     removeClient(channel: string, clientId: string): void;
-    pushToChannel(channel: string, event: SseEvent): void;
+    pushToChannel(channel: string, event: SseEvent): void | Promise<void>;
     getClientCount(channel: string): number;
     getTotalClientCount(): number;
     subscribeAccessInvalidation(userId: string, onInvalidate: () => void, credential?: AccessInvalidationCredential): () => void;
-    publishAccessInvalidation(userId: string, scope?: AccessInvalidationScope): void;
+    publishAccessInvalidation(userId: string, scope?: AccessInvalidationScope): void | Promise<void>;
 };
 export declare function shouldInvalidateListener(credential: AccessInvalidationCredential, scope: AccessInvalidationScope): boolean;
-export declare function createSseBroker(): SseBroker;
+export type LocalSseBroker = Omit<SseBroker, "publishAccessInvalidation" | "pushToChannel"> & {
+    pushToChannel(channel: string, event: SseEvent): void;
+    publishAccessInvalidation(userId: string, scope?: AccessInvalidationScope): void;
+};
+export declare function createSseBroker(): LocalSseBroker;

package/dist/api/sse-route.js

@@ -3,8 +3,9 @@ import { streamSSE } from "hono/streaming";
 import { tenantChannel } from "../engine/constants.js";
 import { isAnonymousSessionUser } from "../engine/system-user.js";
 import { Routes } from "./api-constants.js";
-import { getUser } from "./auth-middleware.js";
+import { getAuthTokenExpiry, getUser } from "./auth-middleware.js";
 import { accessInvalidationCredentialFor } from "./sse-broker.js";
+import { scheduleTokenExpiry } from "./token-expiry-timer.js";
 /**
  * Heartbeat-Cadence für SSE-Streams.
  *
@@ -88,6 +89,9 @@ export function createSseRoute(broker, options) {
         // Channel is server-derived from authenticated user — never trust client input.
         // Allowing ?channel=... would let any authenticated user subscribe to other tenants' feeds.
         const channel = tenantChannel(user.tenantId);
+        // JWT expiry raises no access-invalidation event, so the stream must end
+        // itself when the token it was opened with expires.
+        const tokenExpiresAtSec = getAuthTokenExpiry(c);
         return streamSSE(c, async (stream) => {
             let resolveEnded;
             const ended = new Promise((resolve) => {
@@ -105,6 +109,7 @@ export function createSseRoute(broker, options) {
                 stream.writeSSE({ event: frame.name, data: JSON.stringify(frame.data) });
             }, closeStream);
             const unsubscribeAccessInvalidation = broker.subscribeAccessInvalidation(user.id, closeStream, accessInvalidationCredentialFor(user));
+            const expiryTimer = scheduleTokenExpiry(tokenExpiresAtSec, closeStream);
             let released = false;
             const release = () => {
                 // skip: onAbort and the finally block both release, the second call is a no-op
@@ -113,6 +118,7 @@ export function createSseRoute(broker, options) {
                 released = true;
                 // A client disconnect must also wake the heartbeat sleep, not only a server close.
                 resolveEnded();
+                clearTimeout(expiryTimer);
                 broker.removeClient(channel, clientId);
                 unsubscribeAccessInvalidation();
             };

package/dist/api/token-expiry-timer.d.ts

@@ -0,0 +1 @@
+export declare function scheduleTokenExpiry(tokenExpiresAtSec: number | undefined, onExpired: () => void): ReturnType<typeof setTimeout> | undefined;

package/dist/api/token-expiry-timer.js

@@ -0,0 +1,10 @@
+// setTimeout overflows (fires immediately) above 2^31-1 ms; a token that
+// outlives it just gets its stream recycled early, the client reconnects.
+const MAX_TIMER_DELAY_MS = 2 ** 31 - 1;
+// JWT expiry raises no access-invalidation event, so a long-lived stream must end itself
+// when the token it was opened with expires. Callers clear the returned timer on release.
+export function scheduleTokenExpiry(tokenExpiresAtSec, onExpired) {
+    if (tokenExpiresAtSec === undefined)
+        return undefined;
+    return setTimeout(onExpired, Math.min(MAX_TIMER_DELAY_MS, Math.max(0, tokenExpiresAtSec * 1000 - Date.now())));
+}

package/dist/bun-db/query.js

@@ -309,7 +309,20 @@ function isTemporalPlainDateTimeLike(v) {
 // back deterministically without ever touching a local Date getter — the
 // same +value idiom instantFromDriver uses (guard-no-date-api: no
 // `.getTime()`), just anchored to a fixed zone instead of process-local.
-function plainDateFromDriver(value) {
+// A real `date` column always arrives as a UTC-midnight Date. Anything else means the column is
+// still timestamptz (declared `date` before its ALTER ran); the UTC anchor then silently shifts
+// the day, so say so once per column instead of returning the wrong day quietly.
+const warnedNonMidnightDateColumns = new Set();
+const MS_PER_DAY = 86_400_000;
+const dateColumnDriftLog = createFallbackLogger("bun-db");
+function warnIfNotDateColumn(epochMs, column) {
+    // skip: midnight value is a correct date column, and an already-warned column is deduped
+    if (epochMs % MS_PER_DAY === 0 || warnedNonMidnightDateColumns.has(column))
+        return;
+    warnedNonMidnightDateColumns.add(column);
+    dateColumnDriftLog.warn(`column "${column}" is declared as date but returned a non-midnight timestamp; it is probably still timestamptz. Run the ALTER ... TYPE date migration, otherwise days can shift.`);
+}
+function plainDateFromDriver(value, column) {
     if (value === null || value === undefined)
         return null;
     if (isTemporalPlainDate(value))
@@ -326,6 +339,7 @@ function plainDateFromDriver(value) {
         }
     }
     if (value instanceof Date) {
+        warnIfNotDateColumn(+value, column);
         return Temporal.Instant.fromEpochMilliseconds(+value).toZonedDateTimeISO("UTC").toPlainDate();
     }
     return null;
@@ -357,7 +371,7 @@ export function coerceRow(row, info) {
                 coerced = t;
         }
         else if (pgType === "date") {
-            const d = plainDateFromDriver(value);
+            const d = plainDateFromDriver(value, key);
             if (d !== null)
                 coerced = d;
         }
@@ -507,6 +521,11 @@ function buildWhereClause(info, where, startIndex, qualifier) {
                 parts.push(`${ref(col)} @> $${idx++}${p.sql}`);
                 values.push(p.bound);
             }
+            // A jsonb column holding the scalar itself is never `@>` an array of it.
+            if (isJsonbScalar(v)) {
+                parts.push(`${ref(col)} = $${idx++}::text::jsonb`);
+                values.push(JSON.stringify(v));
+            }
         }
         return parts.length > 0 ? `(${parts.join(" OR ")})` : "FALSE";
     }
@@ -589,14 +608,27 @@ function buildWhereClause(info, where, startIndex, qualifier) {
                     conditions.push("FALSE");
                     continue;
                 }
-                if (opKey === "ne" && pgType === "jsonb" && isJsonbScalar(opVal)) {
-                    const p = prepareJsonbValue([opVal]);
+                // Mirrors applyMultiSelectFilter: an array `ne` means "does not contain all of these".
+                if (opKey === "ne" && pgType === "jsonb" && Array.isArray(opVal)) {
+                    if (opVal.length === 0) {
+                        conditions.push("FALSE");
+                        continue;
+                    }
+                    const p = prepareJsonbValue(opVal);
                     if (p && p.kind === "param") {
                         conditions.push(`(${ref(col)} IS NULL OR NOT (${ref(col)} @> $${idx++}${p.sql}))`);
                         values.push(p.bound);
                         continue;
                     }
                 }
+                if (opKey === "ne" && pgType === "jsonb" && isJsonbScalar(opVal)) {
+                    const p = prepareJsonbValue([opVal]);
+                    if (p && p.kind === "param") {
+                        conditions.push(`(${ref(col)} IS NULL OR NOT (${ref(col)} @> $${idx++}${p.sql} OR ${ref(col)} = $${idx++}::text::jsonb))`);
+                        values.push(p.bound, JSON.stringify(opVal));
+                        continue;
+                    }
+                }
                 const p = prepareValue(opVal, pgType);
                 if (p.kind === "literal") {
                     conditions.push(`${ref(col)} ${opSym} ${p.literal}`);

package/dist/compliance/sub-processors.js

@@ -13,6 +13,11 @@
 // Lead-Time aus dem Compliance-Profile (typisch 30d). Cron-Job kommt
 // in Sprint 1 (compliance-profiles).
 //
+// SubProcessor has no "removed" state yet: a removed entry is deleted from
+// the array, so until the notification cron exists a removal is documented
+// only in the changelog. Removed so far: Mailbox.org (mailbox hosting),
+// replaced by ALL-INKL.COM on 2026-09-02.
+//
 // Quelle: docs/plans/datenschutz/compliance-profiles.md "Sub-Processor-
 // Management" + docs/plans/datenschutz/legal-artifacts.md.
 /**

package/dist/crypto/event-pii.js

@@ -62,8 +62,6 @@ export async function encryptEventPayloadPii(eventType, payload, envelope) {
     if (!piiFields || piiFields === "none")
         return payload;
     const kms = configuredPiiSubjectKms();
-    if (!kms)
-        return payload;
     let out;
     for (const [field, spec] of Object.entries(piiFields)) {
         const value = payload[field];
@@ -75,6 +73,10 @@ export async function encryptEventPayloadPii(eventType, payload, envelope) {
         const subject = resolveEventSubject(field, spec, payload, envelope);
         if (subject === null)
             continue;
+        // Resolved before this skip so a missing owner fails in dev exactly as it
+        // does in prod, instead of surfacing only once a KMS is configured.
+        if (!kms)
+            continue;
         const kmsCtx = { requestId: requestContext.get()?.requestId ?? "append-event" };
         const encrypted = typeof value === "string"
             ? await encryptPiiValueForSubject(kms, subject, value, kmsCtx, field)

package/dist/crypto/kms-wiring.js

@@ -58,7 +58,25 @@ export function buildPgKmsOptions(env) {
         previousKeks: { [previousVersion]: env.PLATFORM_KEK_PREVIOUS },
     };
 }
-function assertTrioConsistent(env, logPrefix) {
+const CIPHERTEXT_CAPABLE_SLOTS = [
+    "PLATFORM_KEK",
+    "PLATFORM_KEK_PREVIOUS",
+    "KUMIKO_BLIND_INDEX_KEY",
+];
+// The sync entry points only read plaintext slots. A ciphertext-only slot
+// would otherwise surface as a misleading "trio required" error or, worse,
+// a silent plaintext-PII fallback in dev.
+function assertNoUnresolvedCiphertext(env, logPrefix) {
+    for (const slot of CIPHERTEXT_CAPABLE_SLOTS) {
+        if (!env[slot] && env[`${slot}_CIPHERTEXT`]) {
+            throw new Error(`${logPrefix ? `${logPrefix} ` : ""}${slot}_CIPHERTEXT is set but ${slot} is not — ` +
+                "the sync KMS wiring cannot resolve ciphertext slots; use resolveKmsWiringAsync / requireKmsWiringAsync.");
+        }
+    }
+}
+function assertTrioConsistent(env, logPrefix, rejectUnresolvedCiphertext) {
+    if (rejectUnresolvedCiphertext)
+        assertNoUnresolvedCiphertext(env, logPrefix);
     const trio = [env.PLATFORM_KEK, env.SUBJECT_KEYS_DATABASE_URL, env.KUMIKO_BLIND_INDEX_KEY];
     const complete = trio.every(Boolean);
     if (!complete && trio.some(Boolean)) {
@@ -81,7 +99,13 @@ function assertTrioConsistent(env, logPrefix) {
  *
  *  Prod entry points that must never fall back: use `requireKmsWiring`. */
 export function resolveKmsWiring(env, options = {}) {
-    const complete = assertTrioConsistent(env, options.logPrefix);
+    return wireKms(env, options, true);
+}
+// The async entry points resolve only their declared slots; a ciphertext slot
+// outside that list is the caller's deliberate choice, so only the sync entry
+// points treat a leftover ciphertext as a wiring error.
+function wireKms(env, options, rejectUnresolvedCiphertext) {
+    const complete = assertTrioConsistent(env, options.logPrefix, rejectUnresolvedCiphertext);
     if (complete && env.PLATFORM_KEK && env.SUBJECT_KEYS_DATABASE_URL && env.KUMIKO_BLIND_INDEX_KEY) {
         const kms = createPgKmsAdapter(buildPgKmsOptions({
             ...env,
@@ -104,7 +128,9 @@ export function resolveKmsWiring(env, options = {}) {
  *  flag so the return type is the active wiring, with no narrowing at the call
  *  site. */
 export function requireKmsWiring(env, options = {}) {
-    const wiring = resolveKmsWiring(env, options);
+    return requireActive(wireKms(env, options, true), options);
+}
+function requireActive(wiring, options) {
     if ("allowPlaintextPii" in wiring) {
         throw new Error(`${options.logPrefix ? `${options.logPrefix} ` : ""}PLATFORM_KEK / ` +
             "SUBJECT_KEYS_DATABASE_URL / KUMIKO_BLIND_INDEX_KEY are required here — " +
@@ -117,9 +143,9 @@ export function requireKmsWiring(env, options = {}) {
  *  `resolvePlatformKeks`. The validation stays in the sync function; this only
  *  adds the KEK-fetching step in front of it. */
 export async function resolveKmsWiringAsync(env, options) {
-    return resolveKmsWiring(await resolvePlatformKeks(env, options), options);
+    return wireKms(await resolvePlatformKeks(env, options), options, false);
 }
 /** Async counterpart to `requireKmsWiring`, KEK-resolving like `resolveKmsWiringAsync`. */
 export async function requireKmsWiringAsync(env, options) {
-    return requireKmsWiring(await resolvePlatformKeks(env, options), options);
+    return requireActive(wireKms(await resolvePlatformKeks(env, options), options, false), options);
 }

package/dist/crypto/pii-field-encryption.d.ts

@@ -1,9 +1,8 @@
 import type { EntityDefinition } from "../engine/types/fields.js";
 import type { TenantId } from "../engine/types/identifiers.js";
-import { type KmsAdapter, type KmsContext, type LocalKeyKmsAdapter, type SubjectId } from "./kms-adapter.js";
+import { type KmsAdapter, type KmsContext, type LocalKeyKmsAdapter, PII_ERASED_SENTINEL, type SubjectId } from "./kms-adapter.js";
 import { isPiiCiphertext, PII_CIPHERTEXT_PREFIX, PII_CIPHERTEXT_PREFIX_JSON } from "./pii-ciphertext-format.js";
-export { isPiiCiphertext, PII_CIPHERTEXT_PREFIX, PII_CIPHERTEXT_PREFIX_JSON };
-export declare const PII_ERASED_SENTINEL = "[[erased]]";
+export { isPiiCiphertext, PII_CIPHERTEXT_PREFIX, PII_CIPHERTEXT_PREFIX_JSON, PII_ERASED_SENTINEL };
 export declare function encryptPiiValueForSubject(kms: LocalKeyKmsAdapter, subject: SubjectId, value: string, kmsCtx: KmsContext, field: string): Promise<string>;
 export declare function encryptPiiJsonValueForSubject(kms: LocalKeyKmsAdapter, subject: SubjectId, value: unknown, kmsCtx: KmsContext, field: string): Promise<string>;
 export declare function decryptPiiValueForSubject(kms: LocalKeyKmsAdapter, value: string, kmsCtx: KmsContext, field: string): Promise<string>;

package/dist/crypto/pii-field-encryption.js

@@ -16,12 +16,11 @@
 // a v2<->v3 prefix swap fails GCM instead of silently changing the type.
 import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
 import { assertIrreversibleOperationAllowed } from "../pipeline/irreversible-operation-gate.js";
-import { isLocalKeyKmsAdapter, KeyAlreadyExistsError, KeyErasedError, KeyNotFoundError, subjectIdFromKey, subjectIdToKey, } from "./kms-adapter.js";
+import { isLocalKeyKmsAdapter, KeyAlreadyExistsError, KeyErasedError, KeyNotFoundError, PII_ERASED_SENTINEL, subjectIdFromKey, subjectIdToKey, } from "./kms-adapter.js";
 import { isPiiCiphertext, PII_CIPHERTEXT_PREFIX, PII_CIPHERTEXT_PREFIX_JSON, PII_CIPHERTEXT_PREFIX_V1, } from "./pii-ciphertext-format.js";
 import { resolveSubjectForField } from "./subject-resolver.js";
 // Spec value (crypto-shredding.md) — renderers show it verbatim.
-export { isPiiCiphertext, PII_CIPHERTEXT_PREFIX, PII_CIPHERTEXT_PREFIX_JSON };
-export const PII_ERASED_SENTINEL = "[[erased]]";
+export { isPiiCiphertext, PII_CIPHERTEXT_PREFIX, PII_CIPHERTEXT_PREFIX_JSON, PII_ERASED_SENTINEL };
 const IV_LENGTH = 12;
 const AUTH_TAG_LENGTH = 16;
 function buildAad(subject, field, isJson) {

package/dist/db/eagerload.d.ts

@@ -1,4 +1,5 @@
-import type { EntityDefinition } from "../engine/types/index.js";
+import type { EntityDefinition, SessionUser } from "../engine/types/index.js";
+import { type ParentVisibilityOption } from "./parent-ref-clause.js";
 import type { TenantDb } from "./tenant-db.js";
 export type EagerLoadEntityResolver = (entityName: string) => EntityDefinition | undefined;
 export type EagerloadedRow<T extends Record<string, unknown> = Record<string, unknown>> = T & {
@@ -10,9 +11,13 @@ type ReferenceFieldEntry = {
     readonly multiple: boolean;
 };
 export declare function collectReferenceFields(entity: EntityDefinition): readonly ReferenceFieldEntry[];
+export type EagerLoadViewer = {
+    readonly user: SessionUser;
+    readonly parentVisibility: ParentVisibilityOption;
+};
 /** Eagerload für eine Liste von Rows. Mutiert nicht — gibt eine
  *  flache Kopie der Rows mit hinzugefügtem `_refs`-Property zurück. */
-export declare function enrichWithReferences(rows: ReadonlyArray<Record<string, unknown>>, entity: EntityDefinition, resolveEntity: EagerLoadEntityResolver, db: TenantDb): Promise<Array<Record<string, unknown>>>;
+export declare function enrichWithReferences(rows: ReadonlyArray<Record<string, unknown>>, entity: EntityDefinition, resolveEntity: EagerLoadEntityResolver, db: TenantDb, viewer: EagerLoadViewer): Promise<Array<Record<string, unknown>>>;
 /** Single-Row-Variante für detail-Calls. */
-export declare function enrichRowWithReferences(row: Record<string, unknown>, entity: EntityDefinition, resolveEntity: EagerLoadEntityResolver, db: TenantDb): Promise<Record<string, unknown>>;
+export declare function enrichRowWithReferences(row: Record<string, unknown>, entity: EntityDefinition, resolveEntity: EagerLoadEntityResolver, db: TenantDb, viewer: EagerLoadViewer): Promise<Record<string, unknown>>;
 export {};