@cosmicdrift/kumiko-framework 0.260.0 → 0.262.0

package/src/engine/boot-validator/__tests__/security-baseline.test.ts

@@ -0,0 +1,107 @@
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import { defineFeature } from "../../define-feature";
+import type { FeatureDefinition } from "../../types";
+import { validateBoot } from "../index";
+import {
+  SECURITY_BASELINE_FEATURE_NAMES,
+  warnOnMissingSecurityBaseline,
+} from "../security-baseline";
+
+function stubFeature(name: string): FeatureDefinition {
+  return defineFeature(name, () => {});
+}
+
+describe("warnOnMissingSecurityBaseline", () => {
+  let warnSpy: ReturnType<typeof spyOn<Console, "warn">>;
+
+  beforeEach(() => {
+    warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+  });
+
+  test("production + no baseline features → warns once, naming all four", () => {
+    warnOnMissingSecurityBaseline([], "production");
+
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    const msg = String(warnSpy.mock.calls[0]?.[0]);
+    for (const name of SECURITY_BASELINE_FEATURE_NAMES) {
+      expect(msg).toContain(name);
+    }
+  });
+
+  test("production + only sessions/audit mounted → warns about the missing two only", () => {
+    const features = [stubFeature("sessions"), stubFeature("audit")];
+
+    warnOnMissingSecurityBaseline(features, "production");
+
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    const msg = String(warnSpy.mock.calls[0]?.[0]);
+    expect(msg).toContain("crypto-shredding");
+    expect(msg).toContain("rate-limiting");
+    expect(msg).not.toContain("missing feature(s): sessions");
+  });
+
+  test("production + all four baseline features mounted → no warning", () => {
+    const features = SECURITY_BASELINE_FEATURE_NAMES.map((name) => stubFeature(name));
+
+    warnOnMissingSecurityBaseline(features, "production");
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  test.each(["development", "test", undefined])(
+    "nodeEnv=%p + no baseline features → no warning",
+    (nodeEnv) => {
+      warnOnMissingSecurityBaseline([], nodeEnv);
+
+      expect(warnSpy).not.toHaveBeenCalled();
+    },
+  );
+
+  test("never throws, regardless of nodeEnv or mounted features", () => {
+    expect(() => warnOnMissingSecurityBaseline([], "production")).not.toThrow();
+    expect(() => warnOnMissingSecurityBaseline([], "development")).not.toThrow();
+    expect(() =>
+      warnOnMissingSecurityBaseline(
+        SECURITY_BASELINE_FEATURE_NAMES.map((name) => stubFeature(name)),
+        "production",
+      ),
+    ).not.toThrow();
+  });
+});
+
+describe("validateBoot + security baseline warning", () => {
+  const originalNodeEnv = process.env["NODE_ENV"];
+  let warnSpy: ReturnType<typeof spyOn<Console, "warn">>;
+
+  beforeEach(() => {
+    warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+    if (originalNodeEnv === undefined) {
+      delete process.env["NODE_ENV"];
+    } else {
+      process.env["NODE_ENV"] = originalNodeEnv;
+    }
+  });
+
+  test("production boot with all four baseline stubs mounted does not throw and does not warn", () => {
+    process.env["NODE_ENV"] = "production";
+    const features = SECURITY_BASELINE_FEATURE_NAMES.map((name) => stubFeature(name));
+
+    expect(() => validateBoot(features)).not.toThrow();
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  test("production boot with no baseline features mounted warns but does not throw", () => {
+    process.env["NODE_ENV"] = "production";
+
+    expect(() => validateBoot([])).not.toThrow();
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+  });
+});

package/src/engine/boot-validator/access-declarations.ts

@@ -0,0 +1,141 @@
+import type { AccessRule, FeatureDefinition, WriteHandlerDef } from "../types";
+import type { EntityDefinition, ResolvedPiiFlags } from "../types/fields";
+import { getZodObjectShape } from "./zod-shape";
+
+type HandlerKind = "write" | "query" | "stream";
+
+// Personal-data annotation check mirrors pii-retention.ts's hasAnonymizableSubjectField,
+// minus tenantOwned: a tenant-scoped field isn't an individual's personal data in the
+// sense openToAll+publicIntake is guarding against.
+function isPersonalDataField(field: unknown): boolean {
+  const annot = field as ResolvedPiiFlags; // @cast-boundary schema-walk — see pii-retention.ts
+  return Boolean(annot.pii || annot.userOwned || annot.recordOwned);
+}
+
+function personalFieldNames(entity: EntityDefinition): ReadonlySet<string> {
+  const names = new Set<string>();
+  for (const [fieldName, field] of Object.entries(entity.fields)) {
+    if (isPersonalDataField(field)) names.add(fieldName);
+  }
+  return names;
+}
+
+function candidatePersonalFieldNames(
+  feature: FeatureDefinition,
+  handlerName: string,
+): ReadonlySet<string> {
+  const mappedEntityName = feature.handlerEntityMappings?.[handlerName];
+  const entities = feature.entities ?? {};
+  if (mappedEntityName) {
+    const entity = entities[mappedEntityName];
+    return entity ? personalFieldNames(entity) : new Set();
+  }
+  const names = new Set<string>();
+  for (const entity of Object.values(entities)) {
+    for (const name of personalFieldNames(entity)) names.add(name);
+  }
+  return names;
+}
+
+// A value that is neither `true` nor an object with a non-empty string `reason`
+// counts as "empty" — catches malformed openToAll from untyped sources too.
+function openToAllReasonIsEmpty(access: AccessRule): boolean {
+  if (!("openToAll" in access)) return false;
+  const openToAll: unknown = access.openToAll;
+  if (openToAll === true) return false;
+  if (typeof openToAll !== "object" || openToAll === null) return true;
+  if (!("reason" in openToAll) || typeof openToAll.reason !== "string") return true;
+  return openToAll.reason.trim().length === 0;
+}
+
+function hasOpenToAll(access: AccessRule): boolean {
+  return "openToAll" in access;
+}
+
+function hasPublicIntake(access: AccessRule): boolean {
+  return "publicIntake" in access && access.publicIntake === true;
+}
+
+function validateOpenToAllReason(
+  feature: FeatureDefinition,
+  kind: HandlerKind,
+  handlerName: string,
+  access: AccessRule,
+): void {
+  // skip: reason is well-formed, nothing to validate
+  if (!openToAllReasonIsEmpty(access)) return;
+  throw new Error(
+    `[Feature ${feature.name}] ${kind} handler "${handlerName}" declares an invalid ` +
+      '{ openToAll: ... } — must be `true` or { reason: "<non-empty explanation>" } ' +
+      "for why any authenticated user may call this handler.",
+  );
+}
+
+function validateEscapeHatchReason(
+  feature: FeatureDefinition,
+  handlerName: string,
+  escapeHatch: WriteHandlerDef["escapeHatch"],
+): void {
+  // 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}] write handler "${handlerName}" declares ` +
+      `{ escapeHatch: { reason: "" } } — the reason must be a non-empty string ` +
+      "explaining why this handler needs db.global() write access.",
+  );
+}
+
+function validatePublicIntakeOnlyOnWrite(
+  feature: FeatureDefinition,
+  kind: HandlerKind,
+  handlerName: string,
+  access: AccessRule,
+): void {
+  // skip: write handlers may declare publicIntake, or it wasn't declared here
+  if (kind === "write" || !hasPublicIntake(access)) return;
+  throw new Error(
+    `[Feature ${feature.name}] ${kind} handler "${handlerName}" declares ` +
+      "{ publicIntake: true } — publicIntake is only meaningful on a write handler " +
+      "(it silences the personal-data + openToAll boot check for the fields a write " +
+      "handler's input accepts).",
+  );
+}
+
+function validateOpenToAllPersonalData(
+  feature: FeatureDefinition,
+  handlerName: string,
+  handler: WriteHandlerDef,
+): void {
+  const access = handler.access;
+  // skip: no openToAll declared, or publicIntake already covers personal data
+  if (!hasOpenToAll(access) || hasPublicIntake(access)) return;
+  const shape = getZodObjectShape(handler.schema);
+  // skip: handler schema isn't a zod object — nothing to inspect
+  if (!shape) return;
+  const personalNames = candidatePersonalFieldNames(feature, handlerName);
+  const offending = Object.keys(shape).filter((key) => personalNames.has(key));
+  // skip: no personal-data fields in the handler's input
+  if (offending.length === 0) return;
+  throw new Error(
+    `[Feature ${feature.name}] write handler "${handlerName}" declares openToAll and ` +
+      `accepts personal-data field(s) ${offending.map((f) => `"${f}"`).join(", ")} without ` +
+      "{ publicIntake: true }. Restrict access to roles, or declare " +
+      "{ publicIntake: true } if any authenticated user may submit this personal data.",
+  );
+}
+
+export function validateAccessDeclarations(feature: FeatureDefinition): void {
+  for (const [handlerName, handler] of Object.entries(feature.writeHandlers)) {
+    validateOpenToAllReason(feature, "write", handlerName, handler.access);
+    validateEscapeHatchReason(feature, handlerName, handler.escapeHatch);
+    validateOpenToAllPersonalData(feature, handlerName, handler);
+  }
+  for (const [handlerName, handler] of Object.entries(feature.queryHandlers)) {
+    validateOpenToAllReason(feature, "query", handlerName, handler.access);
+    validatePublicIntakeOnlyOnWrite(feature, "query", handlerName, handler.access);
+  }
+  for (const [handlerName, handler] of Object.entries(feature.streamHandlers)) {
+    validateOpenToAllReason(feature, "stream", handlerName, handler.access);
+    validatePublicIntakeOnlyOnWrite(feature, "stream", handlerName, handler.access);
+  }
+}

package/src/engine/boot-validator/entity-handler.ts

@@ -143,7 +143,7 @@ export function validateHandlerAccess(feature: FeatureDefinition): void {
       if (!handler.access) {
         throw new Error(
           `${label} handler "${feature.name}:${kind}:${name}" is missing an access rule. ` +
-            `Set { roles: [...] } for role-based access, or { openToAll: true } for any authenticated user.`,
+            `Set { roles: [...] } for role-based access, or { openToAll: { reason: "..." } } for any authenticated user.`,
         );
       }
       validateAnonymousRateLimit(feature.name, kind, name, handler.access, handler.rateLimit);

package/src/engine/boot-validator/index.ts

@@ -1,6 +1,7 @@
 import { validateEntityFieldEncryptionAvailable } from "../../db/entity-field-encryption";
 import { QnTypes, qualifyEntityName } from "../qualified-name";
 import type { FeatureDefinition } from "../types";
+import { validateAccessDeclarations } from "./access-declarations";
 import { warnOnUniqueAccessRoles } from "./access-roles";
 import { validateActionWiring, validateFieldWiring } from "./action-wiring";
 import { validateApiExposureMatching, validateExtensionUsages } from "./api-ext";
@@ -60,6 +61,7 @@ import {
   validateScreenShortIdCollisions,
   validateScreens,
 } from "./screens";
+import { warnOnMissingSecurityBaseline } from "./security-baseline";
 import {
   collectWorkspaceQns,
   validateDefaultWorkspaceUniqueness,
@@ -71,6 +73,7 @@ export { validateAppCustomScreenWriteQns } from "./custom-screen-write-qns";
 // an den Codegen zu übergeben. Nicht Teil von validateBoot, aber
 // dieselbe Extraktionslogik.
 export { collectWriteHandlerQns } from "./nav";
+export { SECURITY_BASELINE_FEATURE_NAMES } from "./security-baseline";
 
 export type ValidateBootOptions = {
   /** Warn when an access role is used by exactly one handler/config-key/
@@ -187,6 +190,7 @@ export function validateBoot(
     validateExtendSchemaCollisions(feature);
     validateDerivedFieldCollisions(feature);
     validateHandlerAccess(feature);
+    validateAccessDeclarations(feature);
     validateLocatedTimestamps(feature);
     validateEntityIndexes(feature);
     validateConfigKeyBounds(feature);
@@ -252,6 +256,7 @@ export function validateBoot(
 
   validateConfigReads(features, allConfigKeys);
   warnOnToggleableDependencies(features, featureMap);
+  warnOnMissingSecurityBaseline(features);
   if (options?.warnOnUniqueAccessRoles === true) {
     warnOnUniqueAccessRoles(features);
   }

package/src/engine/boot-validator/security-baseline.ts

@@ -0,0 +1,26 @@
+import type { FeatureDefinition } from "../types";
+
+export const SECURITY_BASELINE_FEATURE_NAMES = [
+  "sessions",
+  "crypto-shredding",
+  "rate-limiting",
+  "audit",
+] as const;
+
+export function warnOnMissingSecurityBaseline(
+  features: readonly FeatureDefinition[],
+  nodeEnv: string | undefined = process.env["NODE_ENV"],
+): void {
+  // skip: baseline is only enforced for production boots
+  if (nodeEnv !== "production") return;
+
+  const mountedNames = new Set(features.map((f) => f.name));
+  const missing = SECURITY_BASELINE_FEATURE_NAMES.filter((name) => !mountedNames.has(name));
+  // skip: every baseline feature is mounted
+  if (missing.length === 0) return;
+
+  // biome-ignore lint/suspicious/noConsole: boot-time hint, no logger available yet
+  console.warn(
+    `[kumiko:boot] NODE_ENV=production but the security baseline is incomplete — missing feature(s): ${missing.join(", ")}. Mount securityBaselineFeatures() from @cosmicdrift/kumiko-bundled-features/presets (or the missing features individually).`,
+  );
+}

package/src/engine/boot-validator.ts

@@ -1,5 +1,6 @@
 export {
   collectWriteHandlerQns,
+  SECURITY_BASELINE_FEATURE_NAMES,
   type ValidateBootOptions,
   validateAppCustomScreenWriteQns,
   validateBoot,

package/src/engine/define-handler.ts

@@ -85,6 +85,7 @@ export function defineWriteHandler<
       unsafeSkipTransitionGuard: def.unsafeSkipTransitionGuard,
     }),
     ...(def.rateLimit && { rateLimit: def.rateLimit }),
+    ...(def.escapeHatch && { escapeHatch: def.escapeHatch }),
   };
 
   if ("perform" in def && def.perform !== undefined) {

package/src/engine/entity-handlers.ts

@@ -30,6 +30,7 @@ import type {
 } from "./types/entity-handlers";
 
 export type {
+  EntityCrudHandlerDefaults,
   EntityCrudRegistrar,
   EntityCrudVerb,
   EntityHandlerOptions,
@@ -174,7 +175,7 @@ function parseHandlerName<TVerb extends string>(
 export function defineEntityWriteHandler(
   name: string,
   entity: EntityDefinition,
-  options?: EntityHandlerOptions,
+  options: EntityHandlerOptions,
 ): WriteHandlerDef {
   const { entityName, verb } = parseHandlerName(name, WRITE_VERBS);
   if (verb === "restore" && !entity.softDelete) {
@@ -291,9 +292,9 @@ export function defineEntityWriteHandler(
     name,
     schema,
     handler,
-    ...(options?.access && { access: options.access }),
-    ...(options?.description !== undefined && { description: options.description }),
-    ...(options?.agent !== undefined && { agent: options.agent }),
+    access: options.access,
+    ...(options.description !== undefined && { description: options.description }),
+    ...(options.agent !== undefined && { agent: options.agent }),
   };
 }
 
@@ -323,7 +324,7 @@ function augmentDerivedFields(
 export function defineEntityQueryHandler(
   name: string,
   entity: EntityDefinition,
-  options?: EntityQueryHandlerOptions,
+  options: EntityQueryHandlerOptions,
 ): QueryHandlerDef {
   const { entityName, verb } = parseHandlerName(name, QUERY_VERBS);
 
@@ -421,9 +422,9 @@ export function defineEntityQueryHandler(
     name,
     schema,
     handler,
-    ...(options?.access && { access: options.access }),
-    ...(options?.description !== undefined && { description: options.description }),
-    ...(options?.agent !== undefined && { agent: options.agent }),
+    access: options.access,
+    ...(options.description !== undefined && { description: options.description }),
+    ...(options.agent !== undefined && { agent: options.agent }),
     // The "list" verb's executor.list() always returns { rows, nextCursor,
     // total? } (see the handler body above) — brand it so the definition
     // site documents the PagedRows contract without needing
@@ -458,7 +459,7 @@ export function defineEntityQueryHandler(
 export function defineEntityCreateHandler(
   entityName: string,
   entity: EntityDefinition,
-  options?: EntityHandlerOptions,
+  options: EntityHandlerOptions,
 ): WriteHandlerDef {
   return defineEntityWriteHandler(`${entityName}:create`, entity, options);
 }
@@ -467,7 +468,7 @@ export function defineEntityCreateHandler(
 export function defineEntityUpdateHandler(
   entityName: string,
   entity: EntityDefinition,
-  options?: EntityHandlerOptions,
+  options: EntityHandlerOptions,
 ): WriteHandlerDef {
   return defineEntityWriteHandler(`${entityName}:update`, entity, options);
 }
@@ -476,7 +477,7 @@ export function defineEntityUpdateHandler(
 export function defineEntityDeleteHandler(
   entityName: string,
   entity: EntityDefinition,
-  options?: EntityHandlerOptions,
+  options: EntityHandlerOptions,
 ): WriteHandlerDef {
   return defineEntityWriteHandler(`${entityName}:delete`, entity, options);
 }
@@ -485,7 +486,7 @@ export function defineEntityDeleteHandler(
 export function defineEntityRestoreHandler(
   entityName: string,
   entity: EntityDefinition,
-  options?: EntityHandlerOptions,
+  options: EntityHandlerOptions,
 ): WriteHandlerDef {
   return defineEntityWriteHandler(`${entityName}:restore`, entity, options);
 }
@@ -494,7 +495,7 @@ export function defineEntityRestoreHandler(
 export function defineEntityListHandler(
   entityName: string,
   entity: EntityDefinition,
-  options?: EntityQueryHandlerOptions,
+  options: EntityQueryHandlerOptions,
 ): QueryHandlerDef {
   return defineEntityQueryHandler(`${entityName}:list`, entity, options);
 }
@@ -503,7 +504,7 @@ export function defineEntityListHandler(
 export function defineEntityDetailHandler(
   entityName: string,
   entity: EntityDefinition,
-  options?: EntityQueryHandlerOptions,
+  options: EntityQueryHandlerOptions,
 ): QueryHandlerDef {
   return defineEntityQueryHandler(`${entityName}:detail`, entity, options);
 }
@@ -542,7 +543,7 @@ export function createEntityExecutor(
 export function defineProjectionQueryHandler(
   name: string,
   projectionQualifiedName: string,
-  options?: { access?: AccessRule; unsafeAllTenants?: boolean },
+  options: { access: AccessRule; unsafeAllTenants?: boolean },
 ): QueryHandlerDef {
   return {
     name,
@@ -554,9 +555,9 @@ export function defineProjectionQueryHandler(
     handler: async (_query, ctx) =>
       ctx.queryProjection(
         projectionQualifiedName,
-        options?.unsafeAllTenants ? { unsafeAllTenants: true } : undefined,
+        options.unsafeAllTenants ? { unsafeAllTenants: true } : undefined,
       ), // @wrapper-known semantic-alias
-    ...(options?.access && { access: options.access }),
+    access: options.access,
   };
 }
 
@@ -588,14 +589,23 @@ export function registerEntityCrud(
   }
   const writeOpts = options?.write;
   const readOpts = options?.read;
+  const requireAccess = (verb: EntityCrudVerb, access: AccessRule | undefined): AccessRule => {
+    if (!access) {
+      throw new Error(
+        `registerEntityCrud("${entityName}", verb: "${verb}"): no access rule resolved. ` +
+          `Set write.access/read.access on registerEntityCrud's options, or verbAccess.${verb}.`,
+      );
+    }
+    return access;
+  };
   const resolveWriteOpts = (verb: EntityCrudVerb): EntityHandlerOptions => ({
     ...writeOpts,
-    access: options?.verbAccess?.[verb] ?? writeOpts?.access,
+    access: requireAccess(verb, options?.verbAccess?.[verb] ?? writeOpts?.access),
     description: options?.descriptions?.[verb] ?? writeOpts?.description,
   });
   const resolveReadOpts = (verb: EntityCrudVerb): EntityQueryHandlerOptions => ({
     ...readOpts,
-    access: options?.verbAccess?.[verb] ?? readOpts?.access,
+    access: requireAccess(verb, options?.verbAccess?.[verb] ?? readOpts?.access),
     description: options?.descriptions?.[verb] ?? readOpts?.description,
   });
 

package/src/engine/factories.ts

@@ -1,3 +1,4 @@
+import type { EntityTenancy } from "@cosmicdrift/kumiko-types/tenancy-brand";
 import type {
   BigIntFieldDef,
   BooleanFieldDef,
@@ -442,7 +443,7 @@ export function createImagesField(
 // Issue um Constraint-Inferenz auf strukturellen Records. Stattdessen
 // validieren wir die Conformance via conditional return type: wenn F
 // nicht FieldsMap-compat ist, kollabiert der Return zu `never`.
-export function createEntity<F>(def: {
+export function createEntity<F, const T extends EntityTenancy = "tenant">(def: {
   readonly table?: string;
   readonly fields: F;
   readonly description?: string;
@@ -460,7 +461,8 @@ export function createEntity<F>(def: {
   readonly parentRef?: EntityDefinition["parentRef"];
   readonly retention?: RetentionDef;
   readonly derivedFields?: EntityDefinition["derivedFields"];
-}): F extends FieldsMap ? EntityDefinition<F> : never {
+  readonly tenancy?: T;
+}): F extends FieldsMap ? EntityDefinition<F, T> : never {
   return {
     softDelete: false,
     searchWeight: 1,
@@ -468,5 +470,5 @@ export function createEntity<F>(def: {
     // aggregate-ids are UUID. Opt-out with `idType: "serial"` for pre-ES
     // legacy tables (should be rare).
     ...def,
-  } as F extends FieldsMap ? EntityDefinition<F> : never; // @cast-boundary engine-payload
+  } as F extends FieldsMap ? EntityDefinition<F, T> : never; // @cast-boundary engine-payload
 }

package/src/engine/feature-ast/extractors/hooks.ts

@@ -42,8 +42,12 @@ export function readOptionalAccessRule(value: unknown): AccessRule | undefined {
   if (Array.isArray(value["roles"]) && value["roles"].every((r) => typeof r === "string")) {
     return { roles: value["roles"] as readonly string[] };
   }
+  const publicIntake = value["publicIntake"] === true ? { publicIntake: true as const } : {};
   if (value["openToAll"] === true) {
-    return { openToAll: true };
+    return { openToAll: true, ...publicIntake };
+  }
+  if (isPlainObject(value["openToAll"]) && typeof value["openToAll"]["reason"] === "string") {
+    return { openToAll: { reason: value["openToAll"]["reason"] }, ...publicIntake };
   }
   return undefined;
 }