@cosmicdrift/kumiko-framework 0.2.2 → 0.2.3

package/src/compliance/sub-processors.ts

@@ -0,0 +1,152 @@
+// Sub-Processor-Liste der Kumiko-Plattform.
+//
+// Auftragsverarbeiter im Sinne von DSGVO Art. 28 die Kumiko fuer den
+// Plattform-Betrieb einsetzt. Wird oeffentlich exposed unter
+//   /api/compliance/sub-processors        (JSON, Sprint 1)
+//   /api/compliance/sub-processors.rss    (RSS, Sprint 1)
+//   kumiko.so/subprocessors               (HTML, Marketing-Repo)
+//
+// Tenant-Admins muessen ueber Add/Change/Remove informiert werden mit
+// Lead-Time aus dem Compliance-Profile (typisch 30d). Cron-Job kommt
+// in Sprint 1 (compliance-profiles).
+//
+// Quelle: docs/plans/datenschutz/compliance-profiles.md "Sub-Processor-
+// Management" + docs/plans/datenschutz/legal-artifacts.md.
+
+/**
+ * Bundle-Tier-Marker fuer SubProcessor.appliesTo. "all-tiers" matched
+ * unabhaengig vom konkreten Tenant-Bundle (z.B. Hetzner als Hosting-
+ * Provider). Konkrete Tier-Namen koennen per-Tenant gefiltert werden.
+ */
+export type BundleTier = "all-tiers" | "standard" | "business" | "enterprise";
+
+/**
+ * Beschreibt einen Auftragsverarbeiter (Art. 28 DSGVO) der von Kumiko
+ * fuer den Plattform-Betrieb eingesetzt wird.
+ */
+export interface SubProcessor {
+  /** Voller juristischer Name. */
+  readonly name: string;
+  /** Was macht der Sub-Processor fuer uns? */
+  readonly purpose: string;
+  /** Sitz / Datenverarbeitungs-Region. */
+  readonly region: string;
+  /** Link zum Auftragsverarbeitungsvertrag (DPA/AVV). */
+  readonly dpa: string;
+  /** Wann wurde der Sub-Processor zu unserer Plattform hinzugefuegt? */
+  readonly addedAt: string;
+  /**
+   * Welche Bundle-Tiers nutzen diesen Sub-Processor?
+   * Tenants nicht-betroffener Tiers brauchen keine Notification bei
+   * Aenderungen.
+   */
+  readonly appliesTo: readonly BundleTier[];
+  /**
+   * Standard Contractual Clauses (SCC) fuer Drittlandsuebermittlung
+   * abgeschlossen. Pflicht fuer alle Sub-Processors mit Sitz ausserhalb
+   * EU/EWR.
+   */
+  readonly sccRequired?: boolean;
+  /**
+   * Tenant muss explizit aktivieren (z.B. AI-Feature). Ohne Opt-In
+   * werden keine Daten an diesen Sub-Processor gesendet.
+   */
+  readonly optInOnly?: boolean;
+  /**
+   * Business Associate Agreement fuer HIPAA-Customers verfuegbar.
+   * Relevant nur fuer hipaa-healthcare Compliance-Profile.
+   */
+  readonly hipaaBaaAvailable?: boolean;
+  /**
+   * Geplant aber noch nicht aktiv (Vorbereitung fuer kommenden Sprint).
+   * Wird im Sub-Processor-Endpoint als "planned"-Sektion separat
+   * ausgegeben damit Tenants schon Lead-Time bekommen.
+   */
+  readonly status?: "active" | "planned";
+}
+
+/**
+ * Plattform-weite Sub-Processor-Liste.
+ *
+ * Reihenfolge: nach addedAt (aelteste zuerst). Bei Aenderungen
+ * Snapshot-Test im Test-File explizit updaten — der detektiert
+ * stille Aenderungen.
+ */
+export const KUMIKO_SUB_PROCESSORS: readonly SubProcessor[] = [
+  {
+    name: "Hetzner Online GmbH",
+    purpose: "Cloud-Infrastructure (CNPG-Postgres-Cluster, K8s-Pods, Volumes, Object-Storage)",
+    region: "EU (Germany)",
+    dpa: "https://www.hetzner.com/legal/dpa",
+    addedAt: "2024-01-01",
+    appliesTo: ["all-tiers"],
+    status: "active",
+  },
+  {
+    name: "Cloudflare, Inc.",
+    purpose: "DNS, CDN, DDoS-Protection, WAF",
+    region: "Global (US-headquartered)",
+    dpa: "https://www.cloudflare.com/cloudflare-customer-dpa",
+    addedAt: "2024-01-01",
+    appliesTo: ["all-tiers"],
+    sccRequired: true,
+    status: "active",
+  },
+  {
+    name: "Sendinblue SAS (Brevo)",
+    purpose: "Transactional Email Delivery",
+    region: "EU (France)",
+    dpa: "https://www.brevo.com/legal/dpa/",
+    addedAt: "2024-03-01",
+    appliesTo: ["standard", "business", "enterprise"],
+    status: "active",
+  },
+  {
+    name: "Heinlein Hosting (Mailbox.org)",
+    purpose: "Marketing Email Delivery",
+    region: "EU (Germany)",
+    dpa: "https://mailbox.org/de/datenschutzerklaerung",
+    addedAt: "2024-03-01",
+    appliesTo: ["all-tiers"],
+    status: "active",
+  },
+  {
+    name: "Anthropic PBC",
+    purpose: "AI Model Inference (L2 Composition Layer, AI-Foundation)",
+    region: "US",
+    dpa: "https://www.anthropic.com/legal/dpa",
+    addedAt: "2026-06-01",
+    appliesTo: ["business", "enterprise"],
+    sccRequired: true,
+    optInOnly: true,
+    hipaaBaaAvailable: true,
+    status: "planned",
+  },
+  {
+    name: "Stripe, Inc.",
+    purpose: "Payment Processing (Subscription-Stripe-Plugin)",
+    region: "Global (US-headquartered)",
+    dpa: "https://stripe.com/legal/dpa",
+    addedAt: "2026-06-01",
+    appliesTo: ["all-tiers"],
+    sccRequired: true,
+    status: "planned",
+  },
+];
+
+/**
+ * Filter helper — nur aktive Sub-Processors (kein status="planned").
+ * Genutzt vom oeffentlichen JSON-Endpoint (Sprint 1).
+ */
+export function getActiveSubProcessors(): readonly SubProcessor[] {
+  return KUMIKO_SUB_PROCESSORS.filter((sp) => sp.status !== "planned");
+}
+
+/**
+ * Filter helper — nur geplante Sub-Processors (status="planned"). Werden
+ * separat als "demnaechst aktiv"-Sektion ausgegeben damit Tenant-Admins
+ * schon Lead-Time fuer Compliance-Profile-Konfiguration bekommen.
+ */
+export function getPlannedSubProcessors(): readonly SubProcessor[] {
+  return KUMIKO_SUB_PROCESSORS.filter((sp) => sp.status === "planned");
+}

package/src/db/__tests__/big-int-field.test.ts

@@ -0,0 +1,131 @@
+// Unit-Tests fuer den BigInt-Field-Type — Atom 1a aus dem User-Data-
+// Rights Async-Export-Plan.
+//
+// Pinst:
+//   - createBigIntField liefert FieldDefinition.type === "bigInt"
+//   - buildDrizzleTable mappt auf bigint(name, mode:"number"), nicht
+//     integer (32-bit) → kein silent 2 GB-Cap
+//   - Zod-Schema akzeptiert int + safe-integer + lehnt non-int + Float
+//     + non-safe-integer ab
+//   - required + sortable + filterable + default reisen durch
+//
+// Echter DB-Roundtrip-Test (Insert >2^31, Select, identisch zurueck)
+// kommt mit Atom 1b sobald `exportJobEntity.bytesWritten` auf bigInt
+// migriert ist + die existing integration-Tests die Tabelle wieder
+// einrichten — pinst dort auf realer Postgres + Drizzle-customType-
+// Path statt parallel-mock hier.
+
+import { describe, expect, test } from "vitest";
+import { createBigIntField, createEntity, createNumberField } from "../../engine";
+import { buildInsertSchema } from "../../engine/schema-builder";
+import { buildDrizzleTable } from "../table-builder";
+
+function colByName(table: ReturnType<typeof buildDrizzleTable>, dbName: string) {
+  for (const col of Object.values(table) as Array<{
+    name?: string;
+    notNull?: boolean;
+    columnType?: string;
+    dataType?: string;
+  }>) {
+    if (col && typeof col === "object" && col.name === dbName) return col;
+  }
+  throw new Error(`Column ${dbName} not found in table`);
+}
+
+describe("createBigIntField factory", () => {
+  test("liefert FieldDef mit type='bigInt' + default required=false", () => {
+    const f = createBigIntField();
+    expect(f.type).toBe("bigInt");
+    expect(f.required).toBe(false);
+  });
+
+  test("Overrides reisen durch (required, sortable, filterable, default)", () => {
+    const f = createBigIntField({
+      required: true,
+      sortable: true,
+      filterable: true,
+      default: 42,
+    });
+    expect(f.required).toBe(true);
+    expect(f.sortable).toBe(true);
+    expect(f.filterable).toBe(true);
+    expect(f.default).toBe(42);
+  });
+});
+
+describe("buildDrizzleTable — bigInt-Mapping", () => {
+  test("bigInt-Spalte ist DISTINCT von number-Spalte (number=integer/32-bit, bigInt=bigint/64-bit)", () => {
+    const entity = createEntity({
+      fields: {
+        smallCount: createNumberField({}),
+        bigCount: createBigIntField({}),
+      },
+    });
+    const table = buildDrizzleTable("counters", entity);
+
+    const small = colByName(table, "small_count");
+    const big = colByName(table, "big_count");
+
+    // PgInteger vs PgBigint sind unterschiedliche columnType-Klassen in
+    // Drizzle — der genaue String ist Drizzle-Internal aber MUSS
+    // unterschiedlich sein, sonst geht der ganze 64-bit-Punkt verloren.
+    expect(small.columnType).not.toBe(big.columnType);
+  });
+
+  test("required bigInt wird NOT NULL", () => {
+    const entity = createEntity({
+      fields: {
+        requiredBig: createBigIntField({ required: true }),
+        optionalBig: createBigIntField({}),
+      },
+    });
+    const table = buildDrizzleTable("t", entity);
+    expect(colByName(table, "required_big").notNull).toBe(true);
+    expect(colByName(table, "optional_big").notNull).toBe(false);
+  });
+});
+
+describe("buildInsertSchema — bigInt-Validation", () => {
+  test("akzeptiert safe-integer-Werte inkl. >2^31", () => {
+    const entity = createEntity({
+      fields: { bytesWritten: createBigIntField({ required: true }) },
+    });
+    const schema = buildInsertSchema(entity);
+
+    // 2^31 = 2_147_483_648 — Klassisches integer-Overflow-Pattern.
+    expect(schema.parse({ bytesWritten: 2_147_483_648 })).toEqual({
+      bytesWritten: 2_147_483_648,
+    });
+    // 2^50 — weit ueber integer, klar in bigInt-Territorium.
+    expect(schema.parse({ bytesWritten: 2 ** 50 })).toEqual({
+      bytesWritten: 2 ** 50,
+    });
+  });
+
+  test("lehnt Float ab (silent-Truncation-Schutz)", () => {
+    const entity = createEntity({
+      fields: { count: createBigIntField({ required: true }) },
+    });
+    const schema = buildInsertSchema(entity);
+    expect(() => schema.parse({ count: 1.5 })).toThrow();
+  });
+
+  test("lehnt non-safe-integer ab (>2^53)", () => {
+    const entity = createEntity({
+      fields: { count: createBigIntField({ required: true }) },
+    });
+    const schema = buildInsertSchema(entity);
+    // 2^53 = 9_007_199_254_740_992 ist Number.MAX_SAFE_INTEGER.
+    // Werte ueber dem Cap koennen nicht round-trip-en ohne Praezisions-
+    // Verlust — Zod's .safe() greift hier.
+    expect(() => schema.parse({ count: Number.MAX_SAFE_INTEGER + 2 })).toThrow();
+  });
+
+  test("default-Wert reist in Zod-Schema durch", () => {
+    const entity = createEntity({
+      fields: { count: createBigIntField({ default: 100 }) },
+    });
+    const schema = buildInsertSchema(entity);
+    expect(schema.parse({})).toEqual({ count: 100 });
+  });
+});

package/src/db/table-builder.ts

@@ -8,6 +8,7 @@ import type {
 } from "../engine/types";
 import { assertUnreachable } from "../utils";
 import {
+  bigint,
   boolean,
   index,
   instant,
@@ -25,6 +26,7 @@ import {
 type ColumnBuilder =
   | ReturnType<typeof text>
   | ReturnType<typeof integer>
+  | ReturnType<typeof bigint>
   | ReturnType<typeof boolean>
   | ReturnType<typeof moneyAmount>
   | ReturnType<typeof jsonb>
@@ -92,6 +94,15 @@ function fieldToColumns(
       const col = integer(snakeName);
       return { [name]: field.required ? col.notNull() : col };
     }
+    case "bigInt": {
+      // 64-bit-Integer fuer Audit-Counter, Byte-Sizes, Cumulative-Sums.
+      // mode:"number" liefert JS-`number` (sicher bis 2^53 ≈ 9 PB) statt
+      // JS-`bigint` — JSON-serialisierbar, Frontend-tauglich. Wer >2^53
+      // braucht (Astronomie-Astronomie), nutzt einen Text-Field mit
+      // eigenem Codec.
+      const col = bigint(snakeName, { mode: "number" });
+      return { [name]: field.required ? col.notNull() : col };
+    }
     case "reference":
       // Tier 2.7e-3: FK-Style UUID-Spalte. Multi-Mode (Tier 2.7e-Multi)
       // speichert UUIDs als jsonb-Array<string>. Single-Mode bleibt
@@ -467,7 +478,13 @@ export function buildDrizzleTable<E extends EntityDefinition>(
           def.name ?? `${tableName}_${def.columns.map((c) => toSnakeCase(c)).join("_")}_${suffix}`;
         const builder = def.unique === true ? uniqueIndex(indexName) : index(indexName);
         // biome-ignore lint/suspicious/noExplicitAny: drizzle's .on(...cols) is variadic generic
-        indexes.push((builder.on as any)(...cols));
+        let chain = (builder.on as any)(...cols);
+        if (def.where !== undefined) {
+          // Partial-Index: drizzle's IndexBuilder.where(SQL) emittiert das
+          // `WHERE <condition>` ans Ende der `CREATE [UNIQUE] INDEX`-DDL.
+          chain = chain.where(def.where);
+        }
+        indexes.push(chain);
       }
       return indexes;
     },

package/src/engine/__tests__/boot-validator-api-exposure.test.ts

@@ -0,0 +1,142 @@
+// Boot-Validator-Tests fuer r.exposesApi / r.usesApi (S0.4).
+//
+// Pflicht-Validierungen (Error / throw):
+//   - r.usesApi(name) ohne passenden r.exposesApi(name) → throw
+//   - r.usesApi(name) ohne r.requires(providerFeature) → throw
+//   - r.exposesApi(name) zweimal in einem Feature → throw
+//   - Globale Doppel-Exposure (zwei Features, gleicher Name) → throw
+//
+// Soft-Warning (console.warn):
+//   - Feature ruft eigene exposesApi via usesApi (Refactor-Leftover)
+
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { validateBoot } from "../boot-validator";
+import { defineFeature } from "../define-feature";
+
+describe("validateBoot — r.exposesApi / r.usesApi", () => {
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+  });
+
+  test("matching exposesApi/usesApi with requires() passes", () => {
+    const provider = defineFeature("compliance-profiles", (r) => {
+      r.exposesApi("compliance.forTenant");
+    });
+    const consumer = defineFeature("user-data-rights", (r) => {
+      r.requires("compliance-profiles");
+      r.usesApi("compliance.forTenant");
+    });
+    expect(() => validateBoot([provider, consumer])).not.toThrow();
+  });
+
+  test("matching exposesApi/usesApi with optionalRequires() passes", () => {
+    const provider = defineFeature("compliance-profiles", (r) => {
+      r.exposesApi("compliance.forTenant");
+    });
+    const consumer = defineFeature("user-data-rights", (r) => {
+      r.optionalRequires("compliance-profiles");
+      r.usesApi("compliance.forTenant");
+    });
+    expect(() => validateBoot([provider, consumer])).not.toThrow();
+  });
+
+  test("usesApi without any exposer throws with known-list", () => {
+    const consumer = defineFeature("user-data-rights", (r) => {
+      r.usesApi("compliance.forTenant");
+    });
+    expect(() => validateBoot([consumer])).toThrow(
+      /r\.usesApi\("compliance\.forTenant"\) but no feature exposes that API/,
+    );
+  });
+
+  test("usesApi with typo throws and lists known APIs", () => {
+    const provider = defineFeature("compliance-profiles", (r) => {
+      r.exposesApi("compliance.forTenant");
+    });
+    const consumer = defineFeature("user-data-rights", (r) => {
+      r.requires("compliance-profiles");
+      r.usesApi("compliance.fortenant"); // typo: lowercase t
+    });
+    expect(() => validateBoot([provider, consumer])).toThrow(
+      /Known exposed APIs: compliance\.forTenant/,
+    );
+  });
+
+  test("usesApi exists but missing requires() throws", () => {
+    const provider = defineFeature("compliance-profiles", (r) => {
+      r.exposesApi("compliance.forTenant");
+    });
+    const consumer = defineFeature("user-data-rights", (r) => {
+      // missing r.requires("compliance-profiles")
+      r.usesApi("compliance.forTenant");
+    });
+    expect(() => validateBoot([provider, consumer])).toThrow(
+      /not in requires\/optionalRequires\. Add r\.requires\("compliance-profiles"\)/,
+    );
+  });
+
+  test("exposesApi twice in same feature throws", () => {
+    expect(() =>
+      defineFeature("dup", (r) => {
+        r.exposesApi("api.foo");
+        r.exposesApi("api.foo");
+      }),
+    ).toThrow(/r\.exposesApi\("api\.foo"\) called twice/);
+  });
+
+  test("two features expose the same API throws on boot", () => {
+    const a = defineFeature("a", (r) => {
+      r.exposesApi("shared.api");
+    });
+    const b = defineFeature("b", (r) => {
+      r.exposesApi("shared.api");
+    });
+    expect(() => validateBoot([a, b])).toThrow(
+      /Cross-feature API "shared\.api" exposed by both "a" and "b"/,
+    );
+  });
+
+  test("self-exposure (feature uses its own exposed API) warns", () => {
+    const f = defineFeature("self-loop", (r) => {
+      r.exposesApi("self.api");
+      r.usesApi("self.api");
+    });
+    validateBoot([f]);
+    const matchingWarn = warnSpy.mock.calls.find((args: unknown[]) =>
+      String(args[0]).includes("typically a refactor leftover"),
+    );
+    expect(matchingWarn).toBeDefined();
+  });
+
+  test("feature with no API surface boots clean (regression guard)", () => {
+    const plain = defineFeature("plain", (r) => {
+      r.requires();
+    });
+    expect(() => validateBoot([plain])).not.toThrow();
+  });
+
+  test("global double-exposure throws before consumer-resolution kicks in", () => {
+    // Edge-case: zwei Features exposen denselben Namen UND ein drittes
+    // Feature ruft den Namen. Erwartet: Doppel-Exposure-Error wirft im
+    // Pre-Walk (validateBoot) BEVOR validateApiExposureMatching laeuft.
+    const a = defineFeature("provider-a", (r) => {
+      r.exposesApi("shared.api");
+    });
+    const b = defineFeature("provider-b", (r) => {
+      r.exposesApi("shared.api");
+    });
+    const consumer = defineFeature("consumer", (r) => {
+      r.requires("provider-a");
+      r.usesApi("shared.api");
+    });
+    expect(() => validateBoot([a, b, consumer])).toThrow(
+      /Cross-feature API "shared\.api" exposed by both/,
+    );
+  });
+});