@cosmicdrift/kumiko-framework 0.1.0

package/src/db/dialect.ts

@@ -0,0 +1,109 @@
+// Central re-export for all PostgreSQL-specific imports.
+// No other file in the framework should import from "drizzle-orm/pg-core" directly.
+
+import { customType } from "drizzle-orm/pg-core";
+
+export type {
+  PgSelect as SelectQuery,
+  PgTableWithColumns as TableColumns,
+} from "drizzle-orm/pg-core";
+export {
+  bigint,
+  bigserial,
+  boolean,
+  index,
+  integer,
+  jsonb,
+  numeric,
+  pgTable as table,
+  primaryKey,
+  serial,
+  text,
+  timestamp,
+  uniqueIndex,
+  uuid,
+} from "drizzle-orm/pg-core";
+
+/**
+ * Money column: BIGINT storing the integer minor unit (cents for EUR, yen
+ * for JPY). Range ±9.2e18 in the DB; JS `number` is safe to 2^53 ≈ 9e15
+ * minor units = ~90 trillion EUR. INTEGER would cap at ~21 million EUR per
+ * row which is too tight for real-world invoices, bank balances, or bills
+ * of sale — hence bigint.
+ */
+export const moneyAmount = customType<{ data: number; driverData: string | number }>({
+  dataType() {
+    return "bigint";
+  },
+  fromDriver(value: string | number): number {
+    // node-postgres returns BIGINT as string by default; Bun's pg returns
+    // number. Cast via Number() either way — safe because we stay under 2^53.
+    return typeof value === "number" ? value : Number(value);
+  },
+  toDriver(value: number): number {
+    return value;
+  },
+});
+
+/**
+ * Instant column: TIMESTAMPTZ storing a UTC instant, surfaced to JS as
+ * `Temporal.Instant`. Replaces the old dual-mode situation (`mode:"date"`
+ * for base fields vs `mode:"string"` for user-defined timestamp fields)
+ * with a single round-trip type. See sprint-f-temporal.md for the migration.
+ *
+ * Driver-data is the ISO-8601 string the postgres driver actually exchanges.
+ * `fromDriver` reads what the driver returns (postgres-js gives strings for
+ * timestamptz) and parses through Temporal. `toDriver` writes the canonical
+ * Temporal.Instant.toString() — the spike confirmed `eq/lte/gt/orderBy/
+ * returning` accept Temporal.Instant directly without manual `.toString()`
+ * at the call site.
+ *
+ * Boot-order note: `Temporal` must exist on globalThis before any
+ * fromDriver/toDriver call. `ensureTemporalPolyfill()` runs at framework
+ * boot. The closures here are lazy — they fire on read/write, not on
+ * module load — so importing this file before the polyfill is safe.
+ *
+ * Optional `precision` (0..6) — fractional-second digits. Default 6 matches
+ * PG's default `timestamptz`. Pass 3 for the events-table (ms precision —
+ * matches what asOf-queries can compare reliably). Affects only CREATE TABLE
+ * DDL via drizzle-kit; runtime parse handles any precision via Temporal.
+ */
+// Forgiving overload: payloads from custom write-handlers sometimes
+// arrive as ISO strings rather than Temporal.Instant (Zod insert-
+// schemas use z.iso.datetime, not a Temporal validator). Coerce here
+// at the boundary so the DB always sees a normalised string — and
+// Temporal.Instant.from throws on bad input, which is the right failure
+// mode (vs. the obscure "x.toString is not a function" crash that hit
+// feature authors before this overload existed).
+//
+// Date-only strings (YYYY-MM-DD) coercen wir auf start-of-day UTC.
+// Hintergrund: type:"date" ist heute auf instant() aliased (table-
+// builder.ts TODO Sprint G), aber die Zod-Validation akzeptiert nur
+// YYYY-MM-DD. Ohne diesen Coerce wirft Temporal mit "Cannot parse:
+// 2026-04-10" und der Author bekommt einen internal_error 500 statt
+// einen sauberen DB-Roundtrip.
+//
+// Exportiert für Tests; production-call läuft über instantBuilder.
+export function instantToDriver(value: Temporal.Instant | string): string {
+  if (typeof value === "string") {
+    const dateOnly = /^\d{4}-\d{2}-\d{2}$/.test(value);
+    const iso = dateOnly ? `${value}T00:00:00Z` : value;
+    return Temporal.Instant.from(iso).toString();
+  }
+  return value.toString();
+}
+
+const instantBuilder = (config?: { precision?: 0 | 1 | 2 | 3 | 4 | 5 | 6 }) =>
+  customType<{ data: Temporal.Instant; driverData: string }>({
+    dataType() {
+      const p = config?.precision;
+      return p !== undefined ? `timestamp(${p}) with time zone` : "timestamptz";
+    },
+    fromDriver(value: string): Temporal.Instant {
+      return Temporal.Instant.from(value);
+    },
+    toDriver: instantToDriver,
+  });
+export function instant(name: string, config?: { precision?: 0 | 1 | 2 | 3 | 4 | 5 | 6 }) {
+  return instantBuilder(config)(name);
+}

package/src/db/eagerload.ts

@@ -0,0 +1,174 @@
+// Tier 2.7e Server-Side Eagerload für Reference-Felder.
+//
+// Nach `executor.list`/`detail` scannen wir die zurückgelieferten
+// rows nach reference-Field-Values, sammeln pro Reference die UUIDs
+// (deduped), führen einen einzigen WHERE id IN (...)-Lookup pro
+// Referenced-Entity aus, und hängen die resolved Rows als
+// `_refs.<fieldName>` (single) bzw. `_refs.<fieldName>: Row[]`
+// (multiple) an die Original-Rows.
+//
+// Tenant-Scope: TenantDb hat den Tenant-Filter eingebaut (mode:
+// "tenant"); der Lookup erbt das transparent. Cross-Feature-Refs
+// landen automatisch im selben Tenant — falls ein referenced Item
+// dem User nicht gehört, kommt es aus dem Lookup nicht zurück
+// (TenantDb filtert), und der Renderer fällt auf UUID zurück.
+//
+// Limit: kein expliziter limit auf den Lookup-SELECT — wir
+// fragen genau die UUIDs ab die in den main-Rows vorkommen, also
+// O(n) pro Page (bei pageSize:50 mit 2 ref-Spalten = max 100 IDs).
+// Render-Side limit:200-Workaround entfällt damit komplett.
+//
+// Diese Datei lebt im framework/db damit sie an einer Stelle
+// zwischen executor und entity-handlers gemounted ist; sie nutzt
+// keine framework-engine-Internals und kann auch von custom
+// query-handlern manuell aufgerufen werden.
+
+import { inArray } from "drizzle-orm";
+import type { EntityDefinition, FieldDefinition, ReferenceFieldDef } from "../engine/types";
+import { buildDrizzleTable } from "./table-builder";
+import type { TenantDb } from "./tenant-db";
+
+// Minimaler Registry-Lookup-Contract: pro entity-name → EntityDefinition.
+// Wir importieren NICHT den ganzen Registry-Type weil das einen
+// circular import zwischen db/ und engine/ erzeugen würde — der
+// Caller (entity-handlers.ts) hat ctx.registry und reicht hier eine
+// Closure rein.
+export type EagerLoadEntityResolver = (entityName: string) => EntityDefinition | undefined;
+
+// Tier 2.7e Audit-Fix #6: zentral typed Row-Shape mit _refs. Der
+// `_refs`-Property ist Server-Eagerload-Output: pro reference-Field
+// die resolved Row (single) oder ein Array resolved Rows (multiple).
+// Eine reference-Spalte mit value=null hat _refs[fieldName]=undefined.
+//
+// Renderer/Cell-Code liest `row._refs?.[fieldName]` statt inline-Cast;
+// Server-Code stempelt `_refs` über enrichWithReferences. Type ist
+// strukturell — auch Apps die ihre eigenen Refs setzen (Custom-
+// Handler) sollten das hier wiederverwenden.
+export type EagerloadedRow<T extends Record<string, unknown> = Record<string, unknown>> = T & {
+  readonly _refs?: Readonly<
+    Record<string, Record<string, unknown> | ReadonlyArray<Record<string, unknown>> | undefined>
+  >;
+};
+
+type ReferenceFieldEntry = {
+  readonly fieldName: string;
+  readonly refEntityName: string;
+  readonly multiple: boolean;
+};
+
+function isReferenceField(field: FieldDefinition): field is ReferenceFieldDef {
+  return field.type === "reference";
+}
+
+function parseRefEntity(raw: string): string {
+  // Same-feature ("user") oder cross-feature ("users:user") — wir
+  // brauchen nur den entity-name (Names sind global eindeutig in
+  // entityMap). Der feature-prefix dient nur der Author-Klarheit.
+  const idx = raw.indexOf(":");
+  return idx < 0 ? raw : raw.slice(idx + 1);
+}
+
+export function collectReferenceFields(entity: EntityDefinition): readonly ReferenceFieldEntry[] {
+  const out: ReferenceFieldEntry[] = [];
+  for (const [fieldName, fieldDef] of Object.entries(entity.fields)) {
+    if (!isReferenceField(fieldDef)) continue;
+    out.push({
+      fieldName,
+      refEntityName: parseRefEntity(fieldDef.entity),
+      multiple: fieldDef.multiple === true,
+    });
+  }
+  return out;
+}
+
+/** Eagerload für eine Liste von Rows. Mutiert nicht — gibt eine
+ *  flache Kopie der Rows mit hinzugefügtem `_refs`-Property zurück. */
+export async function enrichWithReferences(
+  rows: ReadonlyArray<Record<string, unknown>>,
+  entity: EntityDefinition,
+  resolveEntity: EagerLoadEntityResolver,
+  db: TenantDb,
+): Promise<Array<Record<string, unknown>>> {
+  const refFields = collectReferenceFields(entity);
+  if (refFields.length === 0 || rows.length === 0) {
+    return rows.map((r) => ({ ...r }));
+  }
+
+  // Pro reference-Field: deduped Set der IDs sammeln, dann ein
+  // einziger SELECT WHERE id IN (...). Maps werden parallel gebaut
+  // damit die Lookups nicht serialisieren (Promise.all).
+  const lookupMaps = await Promise.all(
+    refFields.map(async (rf) => {
+      const ids = new Set<string>();
+      for (const row of rows) {
+        const v = row[rf.fieldName];
+        if (rf.multiple) {
+          if (Array.isArray(v)) {
+            for (const item of v) {
+              if (typeof item === "string" && item.length > 0) ids.add(item);
+            }
+          }
+        } else if (typeof v === "string" && v.length > 0) {
+          ids.add(v);
+        }
+      }
+      if (ids.size === 0) return { fieldName: rf.fieldName, multiple: rf.multiple, map: new Map() };
+      const refEntity = resolveEntity(rf.refEntityName);
+      if (refEntity === undefined) {
+        // Author-Fehler oder Race-Condition (entity gerade umbenannt
+        // ohne registry-Reload). Boot-Validator hat das normalerweise
+        // gepinnt; Runtime-Defense: leere Map → Renderer fällt auf
+        // UUID zurück, kein Crash.
+        return { fieldName: rf.fieldName, multiple: rf.multiple, map: new Map() };
+      }
+      const refTable = buildDrizzleTable(rf.refEntityName, refEntity);
+      const idCol = refTable["id"];
+      if (idCol === undefined) {
+        return { fieldName: rf.fieldName, multiple: rf.multiple, map: new Map() };
+      }
+      const idArray = [...ids];
+      const refRows = (await db
+        .select()
+        .from(refTable)
+        .where(inArray(idCol, idArray as never /* @cast-boundary db-operator */))) as Array<
+        Record<string, unknown>
+      >; // @cast-boundary db-row
+      const map = new Map<string, Record<string, unknown>>();
+      for (const r of refRows) {
+        const id = r["id"];
+        if (typeof id === "string") map.set(id, r);
+      }
+      return { fieldName: rf.fieldName, multiple: rf.multiple, map };
+    }),
+  );
+
+  return rows.map((row) => {
+    const refs: Record<string, unknown> = {};
+    for (const lookup of lookupMaps) {
+      const v = row[lookup.fieldName];
+      if (lookup.multiple) {
+        const ids = Array.isArray(v) ? v : [];
+        const resolved = ids
+          .map((id) => (typeof id === "string" ? lookup.map.get(id) : undefined))
+          .filter((r) => r !== undefined);
+        refs[lookup.fieldName] = resolved;
+      } else if (typeof v === "string" && v.length > 0) {
+        refs[lookup.fieldName] = lookup.map.get(v);
+      } else {
+        refs[lookup.fieldName] = undefined;
+      }
+    }
+    return { ...row, _refs: refs };
+  });
+}
+
+/** Single-Row-Variante für detail-Calls. */
+export async function enrichRowWithReferences(
+  row: Record<string, unknown>,
+  entity: EntityDefinition,
+  resolveEntity: EagerLoadEntityResolver,
+  db: TenantDb,
+): Promise<Record<string, unknown>> {
+  const enriched = await enrichWithReferences([row], entity, resolveEntity, db);
+  return enriched[0] ?? { ...row, _refs: {} };
+}

package/src/db/encryption.ts

@@ -0,0 +1,39 @@
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+
+const ALGORITHM = "aes-256-gcm";
+const IV_LENGTH = 12;
+const TAG_LENGTH = 16;
+
+export type EncryptionProvider = {
+  encrypt(plaintext: string): string;
+  decrypt(ciphertext: string): string;
+};
+
+export function createEncryptionProvider(key: string): EncryptionProvider {
+  // Key must be 32 bytes for AES-256
+  const keyBuffer = Buffer.from(key, "base64");
+  if (keyBuffer.length !== 32) {
+    throw new Error("ENCRYPTION_KEY must be 32 bytes (base64 encoded)");
+  }
+
+  return {
+    encrypt(plaintext: string): string {
+      const iv = randomBytes(IV_LENGTH);
+      const cipher = createCipheriv(ALGORITHM, keyBuffer, iv);
+      const encrypted = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+      const tag = cipher.getAuthTag();
+      // Format: base64(iv + tag + ciphertext)
+      return Buffer.concat([iv, tag, encrypted]).toString("base64");
+    },
+
+    decrypt(ciphertext: string): string {
+      const data = Buffer.from(ciphertext, "base64");
+      const iv = data.subarray(0, IV_LENGTH);
+      const tag = data.subarray(IV_LENGTH, IV_LENGTH + TAG_LENGTH);
+      const encrypted = data.subarray(IV_LENGTH + TAG_LENGTH);
+      const decipher = createDecipheriv(ALGORITHM, keyBuffer, iv);
+      decipher.setAuthTag(tag);
+      return decipher.update(encrypted) + decipher.final("utf8");
+    },
+  };
+}