@cosmicdrift/kumiko-framework 0.337.1 → 0.339.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.d.ts

@@ -23,6 +23,7 @@ export type AuthMiddlewareOptions = {
     readonly anonymousAccess?: AnonymousAccessResolved;
     readonly resolveTenantLifecycleStatus?: TenantLifecycleStatusResolver;
     readonly foreignCookieOrigins?: ReadonlySet<string>;
+    readonly isTenantlessAnonymousWrite?: (handlerQn: string) => boolean;
 };
 export type TenantResolver = (c: Context) => Promise<TenantId | null> | TenantId | null;
 export type TenantExists = (tenantId: TenantId) => Promise<boolean> | boolean;

package/dist/api/auth-middleware.js

@@ -1,8 +1,8 @@
 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 { parseTenantId, SYSTEM_TENANT_ID } from "../engine/types/identifiers.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";
@@ -78,7 +78,7 @@ function extractToken(c) {
     return { error: "missing" };
 }
 export function authMiddleware(jwt, options = {}) {
-    const { sessionChecker, anonymousAccess, tokenVerifier, resolveTenantLifecycleStatus, foreignCookieOrigins, } = options;
+    const { sessionChecker, anonymousAccess, tokenVerifier, resolveTenantLifecycleStatus, foreignCookieOrigins, isTenantlessAnonymousWrite, } = options;
     // Fail loud at boot, not silently at request time: a tenantResolver
     // without a declared resolverTrust is an ambiguous trust decision no
     // sane default can make on the app's behalf (see AnonymousAccessConfig).
@@ -87,6 +87,7 @@ export function authMiddleware(jwt, options = {}) {
             'declare "authoritative" (resolver wins over client header/cookie) or ' +
             '"fallback-only" (client wins, resolver is a last resort).');
     }
+    const anonymousExtras = { isTenantlessAnonymousWrite };
     return async (c, next) => {
         const extracted = extractToken(c);
         if ("error" in extracted) {
@@ -109,7 +110,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,
@@ -117,7 +118,7 @@ export function authMiddleware(jwt, options = {}) {
                         i18nKey: "auth.errors.missingToken",
                     });
                 }
-                return await handleAnonymous(c, anonymousAccess, next, resolveTenantLifecycleStatus);
+                return await handleAnonymous(c, anonymousAccess, next, resolveTenantLifecycleStatus, anonymousExtras);
             }
             return middlewareReject(c, {
                 code: "missing_token",
@@ -136,7 +137,7 @@ export function authMiddleware(jwt, options = {}) {
             !c.req.path.startsWith("/api/auth/") &&
             foreignCookieOrigins &&
             isForeignCookieOrigin(c, foreignCookieOrigins)) {
-            return await handleAnonymous(c, anonymousAccess, next, resolveTenantLifecycleStatus);
+            return await handleAnonymous(c, anonymousAccess, next, resolveTenantLifecycleStatus, anonymousExtras);
         }
         // Generic bearer-verifier path: try the wired tokenVerifier (PAT, future
         // JWT-provider, ...) BEFORE jwt.verify. A hit short-circuits the JWT path
@@ -153,7 +154,7 @@ export function authMiddleware(jwt, options = {}) {
         const rejectInvalidCredential = async (rejection) => {
             if (isStaleCookieDowngradable(c, transport, anonymousAccess)) {
                 return await handleAnonymous(c, anonymousAccess, next, resolveTenantLifecycleStatus, {
-                    rejectionIfTenantUnresolved: rejection,
+                    staleCredential: { rejectionIfTenantUnresolved: rejection },
                 });
             }
             return middlewareReject(c, rejection);
@@ -271,7 +272,8 @@ async function handleVerifiedBearerUser(c, user, next, resolveTenantLifecycleSta
 //   5. Synthesise the anonymous SessionUser. The transport flag stays unset
 //      so csrf-middleware skips the double-submit check (no auth-cookie ⇒
 //      no CSRF vector to defend against).
-async function handleAnonymous(c, config, next, resolveTenantLifecycleStatus, staleCredential) {
+async function handleAnonymous(c, config, next, resolveTenantLifecycleStatus, extras = {}) {
+    const { staleCredential, isTenantlessAnonymousWrite } = extras;
     // A downgraded stale credential whose anonymous tenant can't be resolved or
     // is torn down answers with the credential's own 401: a tenant error would
     // hide the session end from the client.
@@ -292,11 +294,14 @@ async function handleAnonymous(c, config, next, resolveTenantLifecycleStatus, st
             ? { id: cookieCheck.tenantId, source: "cookie" }
             : null;
     // Step 3: pick the authoritative tenant.
-    const resolved = await resolveTenant(c, config, clientTenant);
+    const resolved = await resolveTenantOrTenantless(c, config, clientTenant, {
+        allowTenantless: staleCredential === undefined,
+        isTenantlessAnonymousWrite,
+    });
     if ("error" in resolved)
         return rejectTenant(resolved.error);
     // Step 4: existence check for untrusted sources.
-    if (resolved.source !== "default" && config.tenantExists) {
+    if (resolved.source !== "default" && resolved.source !== "tenantless" && config.tenantExists) {
         const exists = await config.tenantExists(resolved.tenantId);
         if (!exists) {
             return rejectTenant({
@@ -308,8 +313,10 @@ async function handleAnonymous(c, config, next, resolveTenantLifecycleStatus, st
             });
         }
     }
-    // Step 5: synthesise + continue.
-    const lifecycleReject = await rejectIfTenantTeardown(c, resolved.tenantId, resolveTenantLifecycleStatus);
+    // Step 5: synthesise + continue. SYSTEM_TENANT_ID is no lifecycle-managed tenant.
+    const lifecycleReject = resolved.source === "tenantless"
+        ? undefined
+        : await rejectIfTenantTeardown(c, resolved.tenantId, resolveTenantLifecycleStatus);
     if (lifecycleReject) {
         return staleCredential
             ? middlewareReject(c, staleCredential.rejectionIfTenantUnresolved)
@@ -321,6 +328,43 @@ async function handleAnonymous(c, config, next, resolveTenantLifecycleStatus, st
     // when next() ran; explicit return makes the union return-type honest.
     return;
 }
+// The exemption applies only where resolveTenant answers tenant_required:
+// never on tenant_mismatch, never when the client named a tenant via X-Tenant,
+// never for a downgraded stale credential. An ambient tenant cookie does not
+// block it: tenant_required with a client tenant only happens when an
+// authoritative resolver stayed silent, and that path ignores the cookie
+// anyway, so a customer who also uses the app on this host can still cancel.
+async function resolveTenantOrTenantless(c, config, clientTenant, tenantless) {
+    const resolved = await resolveTenant(c, config, clientTenant);
+    const { isTenantlessAnonymousWrite } = tenantless;
+    if ("error" in resolved &&
+        resolved.error.code === "tenant_required" &&
+        clientTenant?.source !== "header" &&
+        tenantless.allowTenantless &&
+        isTenantlessAnonymousWrite !== undefined &&
+        (await isFlaggedTenantlessWrite(c, isTenantlessAnonymousWrite))) {
+        return { tenantId: SYSTEM_TENANT_ID, source: "tenantless" };
+    }
+    return resolved;
+}
+// Body peek for the tenantless exemption: only a single-command POST
+// /api/write qualifies, never /api/batch. Parsing the clone leaves the body
+// intact for the dispatcher; the body-size limit already ran upstream.
+async function isFlaggedTenantlessWrite(c, isTenantlessAnonymousWrite) {
+    if (c.req.method !== "POST" || c.req.path !== "/api/write")
+        return false;
+    try {
+        const body = await c.req.raw.clone().json();
+        return (typeof body === "object" &&
+            body !== null &&
+            "type" in body &&
+            typeof body.type === "string" &&
+            isTenantlessAnonymousWrite(body.type));
+    }
+    catch {
+        return false;
+    }
+}
 // Validates an X-Tenant / cookie value against the tenantId format. Returns
 // `{tenantId: null}` when absent, `{tenantId: TenantId}` when valid, or
 // `{error: …}` when the value is non-empty junk (so the caller can return

package/dist/api/routes.d.ts

@@ -1,4 +1,4 @@
-import { Hono } from "hono";
+import { type Context, Hono } from "hono";
 import type { Dispatcher } from "../pipeline/dispatcher.js";
 export declare const StreamFrame: {
     readonly chunk: "chunk";
@@ -18,3 +18,4 @@ export type SseWriter = {
 };
 export declare function pumpStream(stream: SseWriter, generator: AsyncGenerator<unknown>, heartbeatMs: number, firstPull?: Promise<IteratorResult<unknown>>): Promise<void>;
 export declare const MAX_PAYLOAD_DEPTH = 20;
+export declare function handleUncaughtRouteError(err: Error, c: Context): Response | Promise<Response>;

package/dist/api/routes.js

@@ -1,4 +1,5 @@
 import { Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
 import { streamSSE } from "hono/streaming";
 import { AccessDeniedError, reraiseAsKumikoError, serializeError, toKumikoError, ValidationError, } from "../errors/index.js";
 import { createFallbackLogger } from "../logging/index.js";
@@ -356,17 +357,39 @@ function writeErrorResponse(c, err, type) {
     const { error } = serializeError(err, requestId);
     return c.json({ isSuccess: false, error }, err.httpStatus); // @cast-boundary engine-payload
 }
+function clientAbortResponse(c, requestId, type) {
+    logClientWarn("request aborted by client", requestId, type, {
+        status: CLIENT_CLOSED_REQUEST_STATUS,
+    });
+    return c.body(null, CLIENT_CLOSED_REQUEST_STATUS); // @cast-boundary non-standard client-closed-request status, Hono's union doesn't include it
+}
 // For /query + /command: no isSuccess on success (just { data } / {ok}), so we
 // keep the same lean shape on failure — only the `error` key.
 function queryErrorResponse(c, err, type) {
     const requestId = requestContext.get()?.requestId;
-    if (isClientAbort(err)) {
-        logClientWarn("request aborted by client", requestId, type, {
-            status: CLIENT_CLOSED_REQUEST_STATUS,
-        });
-        return c.body(null, CLIENT_CLOSED_REQUEST_STATUS); // @cast-boundary non-standard client-closed-request status, Hono's union doesn't include it
-    }
+    if (isClientAbort(err))
+        return clientAbortResponse(c, requestId, type);
     logServerFault(err, requestId, type);
     const body = serializeError(err, requestId);
     return c.json(body, err.httpStatus); // @cast-boundary engine-payload
 }
+// A raw throw under the request signal (signal.throwIfAborted(), an aborted
+// fetch) is the signal's own reason or wraps it as `cause`.
+function isRequestAbortError(err, signal) {
+    return signal.aborted && (err === signal.reason || err.cause === signal.reason);
+}
+// Root `app.onError`: whatever a route rethrows instead of shaping itself.
+// Without it Hono's default handler console.error()s the bare error and
+// answers an unclassified 500 — including for a client that simply hung up.
+// requestContext only exists under /api/*, so the abort check reads the raw
+// request signal.
+export function handleUncaughtRouteError(err, c) {
+    if (err instanceof HTTPException)
+        return err.getResponse();
+    const requestId = requestContext.get()?.requestId;
+    if (isRequestAbortError(err, c.req.raw.signal))
+        return clientAbortResponse(c, requestId);
+    const kumikoError = toKumiko(err);
+    logServerFault(kumikoError, requestId);
+    return c.json(serializeError(kumikoError, requestId), kumikoError.httpStatus); // @cast-boundary engine-payload
+}

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";
@@ -39,7 +39,7 @@ 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 { createApiRoutes } from "./routes.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";
 // The per-tenant file-provider resolver, built once for a registry+context so
@@ -380,6 +380,8 @@ export function buildServer(options) {
         });
     }
     const app = new Hono();
+    // Sub-apps mounted via app.route() without their own handler inherit this one.
+    app.onError(handleUncaughtRouteError);
     // Only entry:"signature" bypasses jwtGuard (verify() authenticates
     // itself); entry:"anonymous" still needs the anonymousAccess fallthrough
     // (tenant-by-host), entry:"user" needs c.get("user") populated.
@@ -453,7 +455,13 @@ export function buildServer(options) {
     const normalizedForeignCookieOrigins = options.auth?.allowedOrigins?.length
         ? new Set(options.auth.allowedOrigins.map(normalizeOrigin))
         : undefined;
+    const tenantlessAnonymousQns = new Set([...options.registry.getAllWriteHandlers()]
+        .filter(([, handler]) => handler.tenantlessAnonymous === true)
+        .map(([qn]) => qn));
     const jwtGuard = authMiddleware(jwt, {
+        ...(tenantlessAnonymousQns.size > 0
+            ? { isTenantlessAnonymousWrite: (qn) => tenantlessAnonymousQns.has(qn) }
+            : {}),
         ...(options.auth?.sessionChecker ? { sessionChecker: options.auth.sessionChecker } : {}),
         ...(options.auth?.tokenVerifier ? { tokenVerifier: options.auth.tokenVerifier } : {}),
         ...(tenantLifecycleResolver ? { resolveTenantLifecycleStatus: tenantLifecycleResolver } : {}),
@@ -708,6 +716,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/bun-db/query.js

@@ -24,6 +24,7 @@ import { KUMIKO_META_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types
 import { Temporal } from "temporal-polyfill";
 import { requestContext } from "../api/request-context.js";
 import { computeBlindIndex, configuredBlindIndexKey } from "../crypto/blind-index.js";
+import { isPiiCiphertext } from "../crypto/pii-ciphertext-format.js";
 import { SQL_EXPR_BRAND } from "../db/dialect.js";
 import { extractPgError } from "../db/pg-error.js";
 import { toSnakeCase } from "../db/table-builder.js";
@@ -88,7 +89,7 @@ export function asRawClient(db) {
     // closed instead of silently unwrapping a tenant-scoped handle.
     if (isTenantDbShape(db)) {
         throw new Error("asRawClient: received a tenant-scoped TenantDb (ctx.db). Raw SQL helpers do not apply the " +
-            "tenant filter — use a ctx.db.<method>, or ctx.db.unsafeRaw(reason) with escapeHatch: " +
+            "tenant filter — use a ctx.db.<method>, or ctx.db.unsafeRaw() with escapeHatch: " +
             "{ reason } on the handler/hook (r.systemScope() features: ctx.systemDb.unsafeRaw(reason)).");
     }
     // Drizzle DbConnection (legacy compat): $client = postgres-js Sql.
@@ -174,7 +175,7 @@ function tenantDbDelegate(db) {
 function assertNotTenantScoped(db, fnName) {
     if (tenantDbDelegate(db) !== undefined) {
         throw new Error(`${fnName}: received a tenant-scoped db but this helper does not apply the tenant filter. ` +
-            "Pass ctx.db.unsafeRaw(reason) (with escapeHatch: { reason } on the handler/hook) for an " +
+            "Pass ctx.db.unsafeRaw() (with escapeHatch: { reason } on the handler/hook) for an " +
             "explicit cross-tenant op, or use a scoped TenantDb method.");
     }
 }
@@ -462,6 +463,11 @@ function prepareValue(value, pgType) {
     if (isSqlExpression(value)) {
         return { kind: "literal", literal: value.text };
     }
+    // A PII-encrypted jsonb field is a JSON string scalar; a raw string bound to
+    // ::jsonb would be parsed as JSON text (or double-encoded under Bun.SQL).
+    if (pgType === "jsonb" && isPiiCiphertext(value)) {
+        return { kind: "param", sql: "::text::jsonb", bound: JSON.stringify(value) };
+    }
     if (pgType === "jsonb" && value !== null) {
         const prepared = prepareJsonbValue(value);
         if (prepared)

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/crypto/event-pii.js

@@ -14,7 +14,7 @@
 // silent no-op (forgetting the option) is now either an explicit "none" or a
 // missing subject KMS at encrypt-time, both visible states, not a gap.
 import { requestContext } from "../api/request-context.js";
-import { configuredPiiSubjectKms, encryptPiiValueForSubject } from "./pii-field-encryption.js";
+import { configuredPiiSubjectKms, encryptPiiJsonValueForSubject, encryptPiiValueForSubject, } from "./pii-field-encryption.js";
 import { resolveEventSubject } from "./subject-resolver.js";
 import { SYSTEM_EVENT_PII_STANCES, SYSTEM_EVENT_PREFIX } from "./system-event-pii.js";
 // Boot-injected like configurePiiSubjectKms — createRegistry calls this with
@@ -41,6 +41,12 @@ function resolvePiiStance(eventType) {
     }
     return stance;
 }
+// The catalog carries no field types: strings keep the plain format, objects
+// and arrays (jsonb payload fields) use the self-describing JSON format.
+// Bare numbers/booleans stay a loud error so a mistyped string field is caught.
+function isStructuredJsonValue(value) {
+    return typeof value === "object" && value !== null;
+}
 // Encrypts catalogued payload fields under the declared subject's DEK
 // (user/tenant/self — resolveEventSubject, fw#2801). No-op when the event
 // type is uncatalogued or no subject KMS is configured (plaintext rollout
@@ -63,13 +69,16 @@ export async function encryptEventPayloadPii(eventType, payload, envelope) {
         const value = payload[field];
         if (value === null || value === undefined)
             continue;
-        if (typeof value !== "string") {
-            throw new Error(`Event "${eventType}" piiFields."${field}" must be a string payload field, got ${typeof value}`);
+        if (typeof value !== "string" && !isStructuredJsonValue(value)) {
+            throw new Error(`Event "${eventType}" piiFields."${field}" must be a string payload field (or an object/array for jsonb), got ${typeof value}`);
         }
         const subject = resolveEventSubject(field, spec, payload, envelope);
         if (subject === null)
             continue;
-        const encrypted = await encryptPiiValueForSubject(kms, subject, value, { requestId: requestContext.get()?.requestId ?? "append-event" }, field);
+        const kmsCtx = { requestId: requestContext.get()?.requestId ?? "append-event" };
+        const encrypted = typeof value === "string"
+            ? await encryptPiiValueForSubject(kms, subject, value, kmsCtx, field)
+            : await encryptPiiJsonValueForSubject(kms, subject, value, kmsCtx, field);
         if (encrypted !== value) {
             out ??= { ...payload };
             out[field] = encrypted;

package/dist/crypto/index.d.ts

@@ -6,6 +6,6 @@ export { type KekSourceEnv, type KekSourceOptions, resolvePlatformKeks } from ".
 export { isLocalKeyKmsAdapter, KeyAlreadyExistsError, KeyErasedError, KeyNotFoundError, type KmsAdapter, type KmsContext, type KmsHealth, type LocalKeyKmsAdapter, RECORD_ENTITY_PATTERN, type RemoteCryptoKmsAdapter, type SubjectDek, type SubjectId, type SubjectKey, subjectIdFromKey, subjectIdSchema, subjectIdToKey, subjectKeyForRecord, subjectKeyForTenant, subjectKeyForUser, } from "./kms-adapter.js";
 export { type ActiveKmsWiring, buildPgKmsOptions, type KmsWiring, type KmsWiringEnv, type KmsWiringOptions, type KmsWiringRelease, type PgKmsRotationEnv, type PlaintextPiiWiring, requireKmsWiring, requireKmsWiringAsync, resolveKmsWiring, resolveKmsWiringAsync, } from "./kms-wiring.js";
 export { createPgKmsAdapter, PgKmsAdapter, type PgKmsAdapterOptions, type RewrapOptions, type RewrapResult, rewrapSubjectKeys, } from "./pg-kms-adapter.js";
-export { configuredPiiSubjectKms, configurePiiSubjectKms, decryptPiiFieldValues, decryptPiiValueForSubject, type EncryptPiiOptions, encryptPiiFieldValues, encryptPiiValueForSubject, isPiiCiphertext, PII_CIPHERTEXT_PREFIX, PII_ERASED_SENTINEL, } from "./pii-field-encryption.js";
+export { configuredPiiSubjectKms, configurePiiSubjectKms, decryptPiiFieldValues, decryptPiiValueForSubject, type EncryptPiiOptions, encryptPiiFieldValues, encryptPiiJsonValueForSubject, encryptPiiValueForSubject, isPiiCiphertext, PII_CIPHERTEXT_PREFIX, PII_CIPHERTEXT_PREFIX_JSON, PII_ERASED_SENTINEL, } from "./pii-field-encryption.js";
 export { createRequestKmsCache, type RequestKmsCache, } from "./request-kms-cache.js";
 export { collectPiiSubjectFields, collectSearchableSubjectFields, type ResolveSubjectOptions, resolveSubjectForField, SubjectResolutionError, } from "./subject-resolver.js";

package/dist/crypto/index.js

@@ -6,6 +6,6 @@ export { resolvePlatformKeks } from "./kek-source.js";
 export { isLocalKeyKmsAdapter, KeyAlreadyExistsError, KeyErasedError, KeyNotFoundError, RECORD_ENTITY_PATTERN, subjectIdFromKey, subjectIdSchema, subjectIdToKey, subjectKeyForRecord, subjectKeyForTenant, subjectKeyForUser, } from "./kms-adapter.js";
 export { buildPgKmsOptions, requireKmsWiring, requireKmsWiringAsync, resolveKmsWiring, resolveKmsWiringAsync, } from "./kms-wiring.js";
 export { createPgKmsAdapter, PgKmsAdapter, rewrapSubjectKeys, } from "./pg-kms-adapter.js";
-export { configuredPiiSubjectKms, configurePiiSubjectKms, decryptPiiFieldValues, decryptPiiValueForSubject, encryptPiiFieldValues, encryptPiiValueForSubject, isPiiCiphertext, PII_CIPHERTEXT_PREFIX, PII_ERASED_SENTINEL, } from "./pii-field-encryption.js";
+export { configuredPiiSubjectKms, configurePiiSubjectKms, decryptPiiFieldValues, decryptPiiValueForSubject, encryptPiiFieldValues, encryptPiiJsonValueForSubject, encryptPiiValueForSubject, isPiiCiphertext, PII_CIPHERTEXT_PREFIX, PII_CIPHERTEXT_PREFIX_JSON, PII_ERASED_SENTINEL, } from "./pii-field-encryption.js";
 export { createRequestKmsCache, } from "./request-kms-cache.js";
 export { collectPiiSubjectFields, collectSearchableSubjectFields, resolveSubjectForField, SubjectResolutionError, } from "./subject-resolver.js";

package/dist/crypto/pii-ciphertext-format.d.ts

@@ -0,0 +1,4 @@
+export declare const PII_CIPHERTEXT_PREFIX_V1 = "kumiko-pii:v1:";
+export declare const PII_CIPHERTEXT_PREFIX = "kumiko-pii:v2:";
+export declare const PII_CIPHERTEXT_PREFIX_JSON = "kumiko-pii:v3:";
+export declare function isPiiCiphertext(value: unknown): value is string;

package/dist/crypto/pii-ciphertext-format.js

@@ -0,0 +1,11 @@
+// Leaf module (no engine imports) so bun-db and the executors can sniff PII
+// ciphertext without pulling the KMS/pipeline graph into an import cycle.
+export const PII_CIPHERTEXT_PREFIX_V1 = "kumiko-pii:v1:";
+export const PII_CIPHERTEXT_PREFIX = "kumiko-pii:v2:";
+export const PII_CIPHERTEXT_PREFIX_JSON = "kumiko-pii:v3:";
+export function isPiiCiphertext(value) {
+    return (typeof value === "string" &&
+        (value.startsWith(PII_CIPHERTEXT_PREFIX) ||
+            value.startsWith(PII_CIPHERTEXT_PREFIX_JSON) ||
+            value.startsWith(PII_CIPHERTEXT_PREFIX_V1)));
+}

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

@@ -1,10 +1,11 @@
 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 { 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 declare const PII_CIPHERTEXT_PREFIX = "kumiko-pii:v2:";
-export declare function isPiiCiphertext(value: unknown): value is string;
 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>;
 export interface EncryptPiiOptions {
     readonly onlyKeys?: Iterable<string>;
@@ -13,6 +14,7 @@ export interface EncryptPiiOptions {
     readonly entityName: string;
 }
 export declare function encryptPiiFieldValues(row: Record<string, unknown>, entity: EntityDefinition, piiFields: readonly string[], kms: LocalKeyKmsAdapter, kmsCtx: KmsContext, opts: EncryptPiiOptions): Promise<Record<string, unknown>>;
+export declare function serializeJsonbValue(field: string, value: unknown): string;
 export declare function decryptPiiFieldValues(row: Record<string, unknown>, piiFields: readonly string[], kms: LocalKeyKmsAdapter, kmsCtx: KmsContext): Promise<Record<string, unknown>>;
 export declare function configurePiiSubjectKms(adapter: KmsAdapter | undefined): void;
 export declare function configuredPiiSubjectKms(): LocalKeyKmsAdapter | undefined;

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

@@ -9,34 +9,41 @@
 // SAME subject (same DEK, so key selection alone can't catch that) from
 // decrypting silently. v1 (no AAD) stays decrypt-only for pre-#1263 rows;
 // every new write emits v2.
+// v3 = v2 for jsonb fields: the plaintext is JSON.stringify(value) and decrypt
+// JSON.parses it back, so a jsonb string/number/object round-trips by type.
+// The version digit (not a suffix) keeps `kumiko-pii:v\d+:` leak guards and
+// the `kumiko-pii:v%:` LIKE sweeps matching. The AAD carries a "json" tag so
+// 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 { 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]]";
-const PII_CIPHERTEXT_PREFIX_V1 = "kumiko-pii:v1:";
-export const PII_CIPHERTEXT_PREFIX = "kumiko-pii:v2:";
 const IV_LENGTH = 12;
 const AUTH_TAG_LENGTH = 16;
-export function isPiiCiphertext(value) {
-    return (typeof value === "string" &&
-        (value.startsWith(PII_CIPHERTEXT_PREFIX) || value.startsWith(PII_CIPHERTEXT_PREFIX_V1)));
+function buildAad(subject, field, isJson) {
+    return Buffer.from(`${subjectIdToKey(subject)}|${field}${isJson ? "|json" : ""}`, "utf8");
 }
-function buildAad(subject, field) {
-    return Buffer.from(`${subjectIdToKey(subject)}|${field}`, "utf8");
-}
-function encryptValue(subject, dek, plaintext, field) {
+function encryptValue(subject, dek, plaintext, field, isJson = false) {
     const iv = randomBytes(IV_LENGTH);
     const cipher = createCipheriv("aes-256-gcm", dek, iv);
-    cipher.setAAD(buildAad(subject, field));
+    cipher.setAAD(buildAad(subject, field, isJson));
     const ciphertext = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
     const blob = Buffer.concat([iv, cipher.getAuthTag(), ciphertext]);
-    return `${PII_CIPHERTEXT_PREFIX}${subjectIdToKey(subject)}:${blob.toString("base64")}`;
+    const prefix = isJson ? PII_CIPHERTEXT_PREFIX_JSON : PII_CIPHERTEXT_PREFIX;
+    return `${prefix}${subjectIdToKey(subject)}:${blob.toString("base64")}`;
 }
 function parseCiphertext(value) {
-    const hasAad = value.startsWith(PII_CIPHERTEXT_PREFIX);
-    const prefix = hasAad ? PII_CIPHERTEXT_PREFIX : PII_CIPHERTEXT_PREFIX_V1;
+    const isJson = value.startsWith(PII_CIPHERTEXT_PREFIX_JSON);
+    const hasAad = isJson || value.startsWith(PII_CIPHERTEXT_PREFIX);
+    const prefix = isJson
+        ? PII_CIPHERTEXT_PREFIX_JSON
+        : hasAad
+            ? PII_CIPHERTEXT_PREFIX
+            : PII_CIPHERTEXT_PREFIX_V1;
     const rest = value.slice(prefix.length);
     // subjectKey itself contains ":" ("user:<id>") — base64 never does, so the
     // last ":" is always the key/blob separator.
@@ -47,15 +54,16 @@ function parseCiphertext(value) {
         subject: subjectIdFromKey(rest.slice(0, sep)),
         blob: Buffer.from(rest.slice(sep + 1), "base64"),
         hasAad,
+        isJson,
     };
 }
-function decryptValue(dek, blob, subject, field, hasAad) {
+function decryptValue(dek, blob, subject, field, hasAad, isJson) {
     const iv = blob.subarray(0, IV_LENGTH);
     const tag = blob.subarray(IV_LENGTH, IV_LENGTH + AUTH_TAG_LENGTH);
     const ciphertext = blob.subarray(IV_LENGTH + AUTH_TAG_LENGTH);
     const decipher = createDecipheriv("aes-256-gcm", dek, iv);
     if (hasAad)
-        decipher.setAAD(buildAad(subject, field));
+        decipher.setAAD(buildAad(subject, field, isJson));
     decipher.setAuthTag(tag);
     return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
 }
@@ -91,6 +99,12 @@ export async function encryptPiiValueForSubject(kms, subject, value, kmsCtx, fie
     const dek = await getOrCreateDek(kms, subject, kmsCtx);
     return encryptValue(subject, dek, value, field);
 }
+// Event-payload variant for non-string values (jsonb-typed payload fields):
+// same DEK path, but the self-describing v3 format so decrypt restores the type.
+export async function encryptPiiJsonValueForSubject(kms, subject, value, kmsCtx, field) {
+    const dek = await getOrCreateDek(kms, subject, kmsCtx);
+    return encryptValue(subject, dek, serializeJsonbValue(field, value), field, true);
+}
 // Single-value decrypt for callers that don't have an entity/field-map to
 // pass through decryptPiiFieldValues (config values). The subject lives
 // inside the ciphertext itself, so no subject/scope resolution is needed
@@ -99,9 +113,12 @@ export async function encryptPiiValueForSubject(kms, subject, value, kmsCtx, fie
 export async function decryptPiiValueForSubject(kms, value, kmsCtx, field) {
     if (!isPiiCiphertext(value))
         return value;
-    const { subject, blob, hasAad } = parseCiphertext(value);
+    const { subject, blob, hasAad, isJson } = parseCiphertext(value);
+    if (isJson) {
+        throw new Error(`PII field "${field}" holds a jsonb ciphertext — decrypt it via decryptPiiFieldValues`);
+    }
     try {
-        return decryptValue(await kms.getKey(subject, kmsCtx), blob, subject, field, hasAad);
+        return decryptValue(await kms.getKey(subject, kmsCtx), blob, subject, field, hasAad, false);
     }
     catch (e) {
         if (!(e instanceof KeyErasedError))
@@ -127,9 +144,11 @@ export async function encryptPiiFieldValues(row, entity, piiFields, kms, kmsCtx,
         // are already ciphertext or the erased sentinel — both stay as-is.
         if (isPiiCiphertext(value) || value === PII_ERASED_SENTINEL)
             continue;
-        if (typeof value !== "string") {
+        const isJsonbField = entity.fields[name]?.type === "jsonb";
+        if (!isJsonbField && typeof value !== "string") {
             throw new Error(`PII field "${name}" must be a string, got ${typeof value}`);
         }
+        const plaintext = isJsonbField ? serializeJsonbValue(name, value) : String(value);
         const subject = resolveSubjectForField(entity, name, subjectSource, {
             entityName: opts.entityName,
             ...(opts.tenantId !== undefined && { tenantId: opts.tenantId }),
@@ -138,10 +157,17 @@ export async function encryptPiiFieldValues(row, entity, piiFields, kms, kmsCtx,
         if (subject === null)
             continue;
         const dek = await getOrCreateDek(kms, subject, kmsCtx);
-        out[name] = encryptValue(subject, dek, value, name);
+        out[name] = encryptValue(subject, dek, plaintext, name, isJsonbField);
     }
     return out;
 }
+export function serializeJsonbValue(field, value) {
+    const json = JSON.stringify(value);
+    // undefined/function/symbol serialize to undefined — never storable as jsonb
+    if (json === undefined)
+        throw new Error(`PII jsonb field "${field}" is not JSON-serializable`);
+    return json;
+}
 export async function decryptPiiFieldValues(row, piiFields, kms, kmsCtx) {
     if (piiFields.length === 0)
         return row;
@@ -152,9 +178,12 @@ export async function decryptPiiFieldValues(row, piiFields, kms, kmsCtx) {
         // work during rollout; backfill is tracked in kumiko-framework#799).
         if (!isPiiCiphertext(value))
             continue;
-        const { subject, blob, hasAad } = parseCiphertext(value);
+        const { subject, blob, hasAad, isJson } = parseCiphertext(value);
         try {
-            out[name] = decryptValue(await kms.getKey(subject, kmsCtx), blob, subject, name, hasAad);
+            const key = await kms.getKey(subject, kmsCtx);
+            const plain = decryptValue(key, blob, subject, name, hasAad, isJson);
+            // @cast-boundary crypto-decrypt — AEAD-authenticated plaintext that this module serialized
+            out[name] = isJson ? JSON.parse(plain) : plain;
         }
         catch (e) {
             // KeyNotFound deliberately propagates: ciphertext without a key row

package/dist/crypto/system-event-pii.js

@@ -9,8 +9,8 @@ export const SYSTEM_EVENT_PREFIX = "kumiko:system:";
 // an event-store import cycle; transfer.ts re-exports it.
 export const AGGREGATE_TRANSFERRED_EVENT_TYPE = `${SYSTEM_EVENT_PREFIX}aggregate.transferred`;
 const SELF = { personal: "self" };
-// Workflow payloads carry `triggerPayload`, the stored payload of the trigger
-// event: catalogued fields there are already ciphertext, so "none" leaks nothing.
+// Workflow run-stream payloads carry references and step bookkeeping only,
+// never a copy of a foreign event payload, so "none" leaves nothing to shred.
 export const SYSTEM_EVENT_PII_STANCES = new Map([
     [
         STEP_DISPATCH_REQUESTED_TYPE,