@cosmicdrift/kumiko-framework 0.1.0

package/src/engine/field-access.ts

@@ -0,0 +1,120 @@
+import type { DbRow } from "../db/connection";
+import { normalizeAccessEntry, userCanReadFieldRow, userCanWriteFieldRow } from "./ownership";
+import type { EntityDefinition, SessionUser } from "./types";
+
+// Field-level read filtering. Returns a copy of `data` with fields stripped
+// if the user's roles don't grant read access OR the ownership-rule for the
+// matching role doesn't accept this concrete row. Fields without access
+// config are visible to everyone.
+//
+// Removal is silent (field simply not present in the output) — this is the
+// one place in the ownership system where silence is the right default:
+// reporting "you tried to read X but can't" leaks the field's existence.
+// Writes do the opposite (loud error) because a silent drop there masks
+// save-bugs.
+export function filterReadFields(
+  entity: EntityDefinition,
+  data: Readonly<Record<string, unknown>>,
+  user: SessionUser,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(data)) {
+    const field = entity.fields[key];
+    if (!field) {
+      // Base columns (id, tenantId, version, etc.) — always visible
+      result[key] = value;
+      continue;
+    }
+
+    const accessMap = normalizeAccessEntry(field.access?.read);
+    if (!userCanReadFieldRow(user, accessMap, data)) {
+      continue; // entire field stripped
+    }
+
+    // For embedded fields: filter sub-fields with access restrictions
+    if (field.type === "embedded" && value && typeof value === "object") {
+      const filtered: Record<string, unknown> = {};
+      for (const [subKey, subValue] of Object.entries(value as DbRow)) {
+        const subField = field.schema[subKey];
+        const subAccess = normalizeAccessEntry(subField?.access?.read);
+        if (!userCanReadFieldRow(user, subAccess, value as DbRow)) {
+          continue;
+        }
+        filtered[subKey] = subValue;
+      }
+      result[key] = filtered;
+    } else {
+      result[key] = value;
+    }
+  }
+
+  return result;
+}
+
+// Role-only field-write check. Evaluates ONLY whether the user has at
+// least one role mapped to the field's write-access — does NOT evaluate
+// ownership rules against a row. The dispatcher calls this before the
+// handler runs to catch clear-cut role denials (the common case), without
+// needing to load old-row state.
+//
+// Ownership-level row-match for updates happens in the executor, where
+// the pre-update row is already loaded. See checkWriteFieldOwnership.
+//
+// Returns the denied field name, or null if all fields pass the role gate.
+export function checkWriteFieldRoles(
+  entity: EntityDefinition,
+  changes: Readonly<Record<string, unknown>>,
+  user: SessionUser,
+): string | null {
+  for (const key of Object.keys(changes)) {
+    const field = entity.fields[key];
+    if (!field) continue;
+
+    const accessMap = normalizeAccessEntry(field.access?.write);
+    if (!accessMap) continue; // public write
+
+    // Pure role-in-map check — ownership-rule evaluation is deferred.
+    const hasRole = user.roles.some((role) => accessMap[role] !== undefined);
+    if (!hasRole) return key;
+  }
+  return null;
+}
+
+// Full ownership-aware field-write check. Called from the executor after
+// oldRow is loaded. Enforces Straddle-safe per-role atomicity: at least one
+// of the user's roles must accept BOTH the old row AND the new (post-change)
+// row. For creates, pass oldRow = undefined; the check degenerates to a
+// newRow-only evaluation.
+//
+// Returns the denied field name for the caller to wrap into an
+// `ownership_denied` error with scope: "field", or null if all fields pass.
+export function checkWriteFieldOwnership(
+  entity: EntityDefinition,
+  changes: Readonly<Record<string, unknown>>,
+  user: SessionUser,
+  oldRow?: Readonly<Record<string, unknown>>,
+): string | null {
+  for (const key of Object.keys(changes)) {
+    const field = entity.fields[key];
+    if (!field) continue;
+
+    const accessMap = normalizeAccessEntry(field.access?.write);
+    if (!accessMap) continue;
+
+    // Only run the ownership eval when the map actually has at least one
+    // ownership-typed rule (i.e. at least one entry is NOT "all"). Pure
+    // "all" maps are just role-in-map checks — already verified by the
+    // dispatcher, no row-eval needed.
+    const hasOwnershipRule = Object.values(accessMap).some((r) => r !== "all");
+    if (!hasOwnershipRule) continue;
+
+    const newRow: Record<string, unknown> = { ...(oldRow ?? {}), ...changes };
+    const effectiveOld = oldRow ?? newRow; // create: compare against newRow
+
+    if (!userCanWriteFieldRow(user, accessMap, effectiveOld, newRow)) {
+      return key;
+    }
+  }
+  return null;
+}

package/src/engine/index.ts

@@ -0,0 +1,254 @@
+// Public API
+
+export { hasAccess } from "./access";
+export { validateBoot } from "./boot-validator";
+export { buildAppSchema } from "./build-app-schema";
+export { access, createSystemConfig, createTenantConfig, createUserConfig } from "./config-helpers";
+export type { SystemHookName } from "./constants";
+export {
+  ConcurrencyModes,
+  ConfigScopes,
+  LifecycleHookTypes,
+  MessageKind,
+  OnDeleteStrategies,
+  SystemHookNames,
+  SystemHookPriorities,
+  tenantChannel,
+} from "./constants";
+export type { App, AppConfig } from "./create-app";
+export { createApp } from "./create-app";
+export { defineFeature } from "./define-feature";
+export type { QueryHandlerDefinition, WriteHandlerDefinition } from "./define-handler";
+export { defineQueryHandler, defineWriteHandler } from "./define-handler";
+export { defineRoles } from "./define-roles";
+export type { ToggleReader } from "./effective-features";
+export { computeEffectiveFeatures } from "./effective-features";
+export {
+  createEntityExecutor,
+  defineEntityCreateHandler,
+  defineEntityDeleteHandler,
+  defineEntityDetailHandler,
+  defineEntityListHandler,
+  // Legacy single-fn-with-verb-string API. Backwards-compat — neue
+  // Apps nehmen die verb-spezifischen Wrapper oben. Existierende
+  // Caller (Integration-Tests, alte bundled-features) bleiben so
+  // unverändert lauffähig.
+  defineEntityQueryHandler,
+  defineEntityRestoreHandler,
+  defineEntityUpdateHandler,
+  defineEntityWriteHandler,
+  defineProjectionQueryHandler,
+} from "./entity-handlers";
+export type { EmitCtx } from "./event-helpers";
+export { emitEvent, typedPayload } from "./event-helpers";
+export {
+  createBooleanField,
+  createDateField,
+  createEmbeddedField,
+  createEntity,
+  createFileField,
+  createFilesField,
+  createImageField,
+  createImagesField,
+  createLocatedTimestampField,
+  createLongTextField,
+  createMoneyField,
+  createMultiSelectField,
+  createNumberField,
+  createSelectField,
+  createTextField,
+  createTimestampField,
+  createTzField,
+  locatedTimestamp,
+} from "./factories";
+// AST inspection + patching pipeline — used by the CLI scaffolder, the
+// Designer (C5/C6), and the AI-Builder (L2). See feature-ast/index.ts
+// for the full surface area; we re-export the most-used types/functions
+// here so consumers can import everything from a single barrel.
+export type {
+  AddEntityArgs,
+  AddHookArgs,
+  AddRelationArgs,
+  AddWriteHandlerArgs,
+  FeaturePatcher,
+  FeaturePattern,
+  FeaturePatternKind,
+  FormFieldLabel,
+  FormFieldSpec,
+  FormInputType,
+  ParseError,
+  ParseResult,
+  PatternCategory,
+  PatternChange,
+  PatternFormSchema,
+  PatternId,
+  RenderFeatureFileInput,
+  SourceLocation,
+} from "./feature-ast";
+export {
+  addPattern,
+  applyChanges,
+  createFeaturePatcher,
+  getPatternSchema,
+  groupByCategory,
+  PATTERN_LIBRARY,
+  parseFeatureFile,
+  parseSourceFile,
+  removePattern,
+  renderFeatureFile,
+  renderPattern,
+  replacePattern,
+  VERSION_HEADER,
+} from "./feature-ast";
+export {
+  checkWriteFieldOwnership,
+  checkWriteFieldRoles,
+  filterReadFields,
+} from "./field-access";
+export type { OwnershipClause, OwnershipMap, OwnershipRef, OwnershipRule } from "./ownership";
+export { from } from "./ownership";
+export { defineApply, defineMspApply, setFields } from "./projection-helpers";
+export type { BuiltinQnType, ParsedQn, QnType } from "./qualified-name";
+export { isValidQn, parseQn, QnTypes, qn, toKebab } from "./qualified-name";
+export { readClaim } from "./read-claim";
+export { createRegistry } from "./registry";
+export type { ClampInfo, ResolveOptions } from "./resolve-config-or-param";
+export { resolveConfigOrParam } from "./resolve-config-or-param";
+export { runsInLane } from "./run-in";
+export { buildInsertSchema, buildUpdateSchema } from "./schema-builder";
+export type { TransitionGraph } from "./state-machine";
+export { defineTransitions, guardTransition } from "./state-machine";
+export {
+  ANONYMOUS_ROLE,
+  ANONYMOUS_USER_ID,
+  createAnonymousUser,
+  createSystemUser,
+  SYSTEM_ROLE,
+  SYSTEM_USER_ID,
+} from "./system-user";
+// Types
+export type {
+  AccessRule,
+  ActionFormScreenDefinition,
+  AppContext,
+  AppendEventArgs,
+  AppendEventFn,
+  AppendEventUnsafeFn,
+  AuthClaimsContext,
+  AuthClaimsFn,
+  AuthClaimsHookDef,
+  BelongsToRelation,
+  BooleanFieldDef,
+  CamelToKebab,
+  ClaimKeyDefinition,
+  ClaimKeyHandle,
+  ClaimKeyJsType,
+  ClaimKeyType,
+  ConcurrencyMode,
+  ConfigAccessor,
+  ConfigAccessorFactory,
+  ConfigDefinition,
+  ConfigEditScreenDefinition,
+  ConfigKeyAccess,
+  ConfigKeyDefinition,
+  ConfigKeyHandle,
+  ConfigKeyType,
+  ConfigResolver,
+  ConfigScope,
+  ConfigStoredRow,
+  ConfigValue,
+  ConfigValueSource,
+  ConfigValueWithSource,
+  CustomScreenDefinition,
+  CustomScreenRoute,
+  DateFieldDef,
+  DeleteContext,
+  EditFieldSpec,
+  EditLayout,
+  EditSectionSpec,
+  EntityDefinition,
+  EntityEditScreenDefinition,
+  EntityId,
+  EntityListScreenDefinition,
+  EntityRef,
+  EntityRelations,
+  EventDef,
+  FeatureDefinition,
+  FeatureRegistrar,
+  FieldAccess,
+  FieldCondition,
+  FieldDefinition,
+  FieldRenderer,
+  FileFieldDef,
+  FilesFieldDef,
+  HandlerContext,
+  HasManyRelation,
+  HookMap,
+  ImageFieldDef,
+  ImagesFieldDef,
+  JobContext,
+  JobDefinition,
+  JobHandlerFn,
+  JobTrigger,
+  KumikoEntityTypeMap,
+  KumikoEventTypeMap,
+  KumikoHandlerPayloadMap,
+  KumikoHandlerResultMap,
+  LifecycleHookType,
+  ListColumnSpec,
+  ManyToManyRelation,
+  MspErrorMode,
+  MspErrorPolicy,
+  MultiSelectFieldDef,
+  MultiStreamApplyFn,
+  MultiStreamProjectionDefinition,
+  NameOrRef,
+  NavDefinition,
+  NotificationDataFn,
+  NotificationDefinition,
+  NotificationRecipientFn,
+  NotificationTemplateFn,
+  NotifyFactory,
+  NotifyFn,
+  NotifyOptions,
+  NotifyPriority,
+  NumberFieldDef,
+  OnDeleteStrategy,
+  PlatformComponent,
+  PostDeleteHookFn,
+  PostSaveHookFn,
+  PreDeleteHookFn,
+  PreQueryHookFn,
+  PreSaveHookFn,
+  ProjectionDefinition,
+  ProjectionTable,
+  QualifiedEventName,
+  QueryEvent,
+  QueryHandlerDef,
+  QueryHandlerFn,
+  Registry,
+  RelationDefinition,
+  RowAction,
+  SaveContext,
+  ScreenDefinition,
+  ScreenSlots,
+  SelectFieldDef,
+  SessionUser,
+  TenantId,
+  TextFieldDef,
+  ToolbarAction,
+  TranslationKeys,
+  TranslationsDef,
+  ValidationError,
+  ValidationHookFn,
+  WorkspaceDefinition,
+  WriteEvent,
+  WriteHandlerDef,
+  WriteHandlerFn,
+  WriteResult,
+} from "./types";
+export { DEFAULT_CURRENCIES, HookPhases } from "./types";
+export { resolveName, withResponseData } from "./types/handlers";
+export { isSystemTenant, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers";
+export { normalizeEditField, normalizeListColumn } from "./types/screen";
+export { runValidation } from "./validation";