@cosmicdrift/kumiko-bundled-features 0.1.0

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@cosmicdrift/kumiko-bundled-features",
+  "version": "0.1.0",
+  "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
+  "license": "BUSL-1.1",
+  "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cosmicdriftgamestudio/kumiko-framework.git",
+    "directory": "packages/bundled-features"
+  },
+  "bugs": {
+    "url": "https://github.com/cosmicdriftgamestudio/kumiko-framework/issues"
+  },
+  "homepage": "https://kumiko.so",
+  "type": "module",
+  "kumiko": {
+    "runtime": "runtime"
+  },
+  "exports": {
+    "./audit": "./src/audit/index.ts",
+    "./config": "./src/config/index.ts",
+    "./jobs": "./src/jobs/index.ts",
+    "./tier-engine": "./src/tier-engine/index.ts",
+    "./cap-counter": "./src/cap-counter/index.ts",
+    "./billing-foundation": "./src/billing-foundation/index.ts",
+    "./subscription-stripe": "./src/subscription-stripe/index.ts",
+    "./subscription-mollie": "./src/subscription-mollie/index.ts",
+    "./foundation-shared": "./src/foundation-shared/index.ts",
+    "./mail-foundation": "./src/mail-foundation/index.ts",
+    "./mail-transport-smtp": "./src/mail-transport-smtp/index.ts",
+    "./mail-transport-inmemory": "./src/mail-transport-inmemory/index.ts",
+    "./file-foundation": "./src/file-foundation/index.ts",
+    "./file-provider-s3": "./src/file-provider-s3/index.ts",
+    "./file-provider-inmemory": "./src/file-provider-inmemory/index.ts",
+    "./tenant": "./src/tenant/index.ts",
+    "./tenant/constants": "./src/tenant/constants.ts",
+    "./tenant/seeding": "./src/tenant/seeding.ts",
+    "./tenant/testing": "./src/tenant/testing.ts",
+    "./user": "./src/user/index.ts",
+    "./user/seeding": "./src/user/seeding.ts",
+    "./user/testing": "./src/user/testing.ts",
+    "./auth-email-password": "./src/auth-email-password/index.ts",
+    "./auth-email-password/constants": "./src/auth-email-password/constants.ts",
+    "./auth-email-password/seeding": "./src/auth-email-password/seeding.ts",
+    "./auth-email-password/testing": "./src/auth-email-password/testing.ts",
+    "./auth-email-password/web": "./src/auth-email-password/web/index.ts",
+    "./delivery": "./src/delivery/index.ts",
+    "./channel-in-app": "./src/channel-in-app/index.ts",
+    "./channel-email": "./src/channel-email/index.ts",
+    "./channel-push": "./src/channel-push/index.ts",
+    "./renderer-simple": "./src/renderer-simple/index.ts",
+    "./files-provider-s3": "./src/files-provider-s3/index.ts",
+    "./rate-limiting": "./src/rate-limiting/index.ts",
+    "./secrets": "./src/secrets/index.ts",
+    "./sessions": "./src/sessions/index.ts",
+    "./sessions/testing": "./src/sessions/testing.ts",
+    "./feature-toggles": "./src/feature-toggles/index.ts",
+    "./text-content": "./src/text-content/index.ts",
+    "./text-content/seeding": "./src/text-content/seeding.ts",
+    "./legal-pages": "./src/legal-pages/index.ts"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.700.0",
+    "@aws-sdk/s3-request-presigner": "^3.700.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "workspace:*",
+    "@cosmicdrift/kumiko-framework": "workspace:*",
+    "@cosmicdrift/kumiko-renderer": "workspace:*",
+    "@cosmicdrift/kumiko-renderer-web": "workspace:*",
+    "@mollie/api-client": "^4.5.0",
+    "@node-rs/argon2": "^2.0.2",
+    "@types/nodemailer": "^8.0.0",
+    "clsx": "^2.1.1",
+    "lucide-react": "^1.11.0",
+    "marked": "^14.1.3",
+    "nodemailer": "^8.0.7",
+    "react": "^19.2.0",
+    "stripe": "^22.1.0",
+    "tailwind-merge": "^3.0.2"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/audit/__tests__/audit.integration.ts

@@ -0,0 +1,328 @@
+// Audit query — filter-by-example coverage over the event-store. The event
+// log IS the audit trail; this suite proves the query handler exposes the
+// right slices of it (tenant-isolated, filtered, paginated, content-intact).
+
+import {
+  createEntity,
+  createTextField,
+  defineEntityWriteHandler,
+  defineFeature,
+  type SessionUser,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createEntityTable,
+  createTestUser,
+  resetEventStore,
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  testTenantId,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { sql } from "drizzle-orm";
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
+import { AuditQueries } from "../constants";
+import { createAuditFeature } from "../feature";
+
+const widgetEntity = createEntity({
+  table: "audit_widgets",
+  fields: {
+    name: createTextField({ required: true }),
+    color: createTextField(),
+  },
+});
+
+const widgetFeature = defineFeature("widgets", (r) => {
+  r.entity("widget", widgetEntity);
+  for (const verb of ["create", "update", "delete"] as const) {
+    r.writeHandler(
+      defineEntityWriteHandler(`widget:${verb}`, widgetEntity, {
+        access: { roles: ["Admin", "User", "SystemAdmin"] },
+      }),
+    );
+  }
+});
+
+let stack: TestStack;
+
+const admin = TestUsers.systemAdmin;
+const regularUser: SessionUser = createTestUser({
+  id: 7,
+  tenantId: testTenantId(1),
+  roles: ["User"],
+});
+const otherTenantAdmin: SessionUser = createTestUser({
+  id: 8,
+  tenantId: testTenantId(2),
+  roles: ["Admin"],
+});
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [widgetFeature, createAuditFeature()],
+  });
+  await createEntityTable(stack.db, widgetEntity);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  // Fresh event log per test — the audit query reads the events table
+  // directly, so stale events from previous tests would leak into results.
+  await resetEventStore(stack);
+  await stack.db.execute(sql`TRUNCATE audit_widgets`);
+});
+
+async function createWidget(user: SessionUser, name: string, color?: string): Promise<string> {
+  const res = await stack.http.writeOk<{ id: string }>(
+    "widgets:write:widget:create",
+    { name, ...(color && { color }) },
+    user,
+  );
+  return res.id;
+}
+
+type AuditRow = {
+  id: string;
+  aggregateId: string;
+  aggregateType: string;
+  type: string;
+  createdBy: string;
+  createdAt: string;
+  payload: Record<string, unknown>;
+  metadata: Record<string, unknown>;
+};
+
+type AuditResponse = { rows: AuditRow[]; nextBefore: string | null };
+
+describe("audit: list query", () => {
+  test("returns events of the caller's tenant, newest first", async () => {
+    await createWidget(admin, "A");
+    await createWidget(admin, "B");
+    await createWidget(admin, "C");
+
+    const res = await stack.http.queryOk<AuditResponse>(AuditQueries.list, {}, admin);
+    expect(res.rows.length).toBeGreaterThanOrEqual(3);
+    const names = res.rows.map((r) => r.type);
+    expect(names).toContain("widget.created");
+    // Descending by id (bigserial) ⇒ newest first.
+    for (let i = 1; i < res.rows.length; i++) {
+      const prev = BigInt(res.rows[i - 1]!.id);
+      const curr = BigInt(res.rows[i]!.id);
+      expect(prev > curr).toBe(true);
+    }
+  });
+
+  test("tenant isolation: admin on tenant-1 sees NO events from tenant-2", async () => {
+    await createWidget(admin, "on-tenant-1");
+    await stack.http.writeOk<{ id: string }>(
+      "widgets:write:widget:create",
+      { name: "on-tenant-2" },
+      otherTenantAdmin,
+    );
+
+    const res = await stack.http.queryOk<AuditResponse>(AuditQueries.list, {}, admin);
+    for (const r of res.rows) {
+      // Only admin's rows come back — the cross-tenant event's createdBy
+      // would be the other-tenant admin's id.
+      expect(r.createdBy).toBe(admin.id);
+    }
+  });
+
+  test("filter by eventType", async () => {
+    const id1 = await createWidget(admin, "X");
+    await stack.http.writeOk(
+      "widgets:write:widget:update",
+      { id: id1, version: 1, changes: { color: "red" } },
+      admin,
+    );
+    await stack.http.writeOk("widgets:write:widget:delete", { id: id1 }, admin);
+
+    const updates = await stack.http.queryOk<AuditResponse>(
+      AuditQueries.list,
+      { eventType: "widget.updated" },
+      admin,
+    );
+    expect(updates.rows).toHaveLength(1);
+    expect(updates.rows[0]?.type).toBe("widget.updated");
+
+    const deletes = await stack.http.queryOk<AuditResponse>(
+      AuditQueries.list,
+      { eventType: "widget.deleted" },
+      admin,
+    );
+    expect(deletes.rows).toHaveLength(1);
+    expect(deletes.rows[0]?.type).toBe("widget.deleted");
+  });
+
+  test("filter by aggregateId pins the event chain for one entity", async () => {
+    const a = await createWidget(admin, "A");
+    const b = await createWidget(admin, "B");
+    await stack.http.writeOk(
+      "widgets:write:widget:update",
+      { id: a, version: 1, changes: { color: "blue" } },
+      admin,
+    );
+
+    const res = await stack.http.queryOk<AuditResponse>(
+      AuditQueries.list,
+      { aggregateId: a },
+      admin,
+    );
+    expect(res.rows).toHaveLength(2);
+    expect(res.rows.every((r) => r.aggregateId === a)).toBe(true);
+    expect(res.rows.some((r) => r.aggregateId === b)).toBe(false);
+  });
+
+  test("filter by userId", async () => {
+    await createWidget(admin, "by admin");
+    await createWidget(regularUser, "by user");
+
+    const res = await stack.http.queryOk<AuditResponse>(
+      AuditQueries.list,
+      { userId: regularUser.id },
+      admin,
+    );
+    expect(res.rows).toHaveLength(1);
+    expect(res.rows[0]?.createdBy).toBe(regularUser.id);
+  });
+
+  test("filter by from/to date range (inclusive bounds, outside-range rows excluded)", async () => {
+    // Events are written with server-now at ms precision. Delays between
+    // writes + anchor timestamps give us clean sort-order. The anchors are
+    // captured OUTSIDE the write bursts so precision-truncation on the
+    // db side (ms) can't blur anchor vs event.
+    await createWidget(admin, "before-window");
+    await new Promise((r) => setTimeout(r, 50));
+    const t1 = Temporal.Now.instant();
+    await new Promise((r) => setTimeout(r, 10));
+    await createWidget(admin, "in-window-1");
+    await createWidget(admin, "in-window-2");
+    await new Promise((r) => setTimeout(r, 50));
+    const t2 = Temporal.Now.instant();
+    await new Promise((r) => setTimeout(r, 10));
+    await createWidget(admin, "after-window");
+
+    // Slice strictly to the [t1, t2] window — should return exactly 2 rows.
+    const inWindow = await stack.http.queryOk<AuditResponse>(
+      AuditQueries.list,
+      { from: t1.toString(), to: t2.toString() },
+      admin,
+    );
+    expect(inWindow.rows).toHaveLength(2);
+    const names = inWindow.rows.map((r) => (r.payload as { name?: string }).name).sort();
+    expect(names).toEqual(["in-window-1", "in-window-2"]);
+
+    // From-only: everything at or after t1 → 3 rows (2 in-window + 1 after).
+    const sinceT1 = await stack.http.queryOk<AuditResponse>(
+      AuditQueries.list,
+      { from: t1.toString() },
+      admin,
+    );
+    expect(sinceT1.rows).toHaveLength(3);
+
+    // To-only: everything at or before t1 → just the before-window row.
+    const untilT1 = await stack.http.queryOk<AuditResponse>(
+      AuditQueries.list,
+      { to: t1.toString() },
+      admin,
+    );
+    expect(untilT1.rows).toHaveLength(1);
+    expect((untilT1.rows[0]?.payload as { name?: string }).name).toBe("before-window");
+  });
+
+  test("rejects inverted from/to range with validation_error", async () => {
+    // from > to would silently return empty — confusing. Schema-level refine
+    // turns it into a clean 400 at the gate.
+    const res = await stack.http.query(
+      AuditQueries.list,
+      { from: "2030-01-01T00:00:00Z", to: "2020-01-01T00:00:00Z" },
+      admin,
+    );
+    expect(res.status).toBe(400);
+  });
+
+  test("rejects non-numeric cursor with validation_error (no PG crash path)", async () => {
+    // Pre-fix the handler interpolated `before` directly as bigint, so
+    // "abc" would raise an uncaught invalid_text_representation from PG.
+    // The schema regex catches it at the gate.
+    const res = await stack.http.query(AuditQueries.list, { before: "not-a-number" }, admin);
+    expect(res.status).toBe(400);
+  });
+
+  test("pagination: limit + nextBefore cursor walks the log", async () => {
+    for (let i = 0; i < 5; i++) {
+      await createWidget(admin, `W${i}`);
+    }
+
+    const page1 = await stack.http.queryOk<AuditResponse>(AuditQueries.list, { limit: 2 }, admin);
+    expect(page1.rows).toHaveLength(2);
+    expect(page1.nextBefore).not.toBeNull();
+
+    const page2 = await stack.http.queryOk<AuditResponse>(
+      AuditQueries.list,
+      { limit: 2, before: page1.nextBefore },
+      admin,
+    );
+    expect(page2.rows).toHaveLength(2);
+    const page1Ids = page1.rows.map((r) => r.id);
+    const page2Ids = page2.rows.map((r) => r.id);
+    for (const id of page2Ids) expect(page1Ids).not.toContain(id);
+
+    const page3 = await stack.http.queryOk<AuditResponse>(
+      AuditQueries.list,
+      { limit: 2, before: page2.nextBefore },
+      admin,
+    );
+    // 5 events, 2+2+1: final page is partial ⇒ nextBefore null.
+    expect(page3.rows).toHaveLength(1);
+    expect(page3.nextBefore).toBeNull();
+  });
+
+  test("response carries the full event payload + metadata (the audit-relevant detail)", async () => {
+    const id = await createWidget(admin, "Auditable", "green");
+    await stack.http.writeOk(
+      "widgets:write:widget:update",
+      { id, version: 1, changes: { color: "yellow" } },
+      admin,
+    );
+
+    const res = await stack.http.queryOk<AuditResponse>(
+      AuditQueries.list,
+      { aggregateId: id },
+      admin,
+    );
+    // Two events on this stream: created + updated. Newest first.
+    expect(res.rows).toHaveLength(2);
+    const [updated, created] = res.rows;
+
+    // created: payload IS the initial entity snapshot.
+    expect(created?.type).toBe("widget.created");
+    expect(created?.payload).toMatchObject({ name: "Auditable", color: "green" });
+    // metadata carries the actor (userId) for the write.
+    expect(created?.metadata).toMatchObject({ userId: admin.id });
+
+    // updated: payload is { changes, previous } — both halves matter for audit.
+    expect(updated?.type).toBe("widget.updated");
+    expect(updated?.payload).toMatchObject({
+      changes: { color: "yellow" },
+      previous: expect.objectContaining({ color: "green", name: "Auditable" }),
+    });
+    expect(updated?.metadata).toMatchObject({ userId: admin.id });
+  });
+
+  test("access denied for non-admin roles", async () => {
+    await createWidget(admin, "A");
+    // regularUser has role "User" — the handler requires Admin/SystemAdmin.
+    const res = await stack.http.query(AuditQueries.list, {}, regularUser);
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as {
+      error?: { code?: string; details?: { reason?: string } };
+    };
+    // Pin the specific failure class. The framework raises AccessDeniedError
+    // with code=access_denied; asserting on `code` beats a status-only check
+    // (a 403 could also come from ownership-denied, for example).
+    expect(body.error?.code).toBe("access_denied");
+  });
+});

package/src/audit/constants.ts

@@ -0,0 +1,7 @@
+// Qualified handler names — kept in one place so tests/clients can reference
+// the audit query without hard-coding the full string.
+export const AUDIT_FEATURE = "audit" as const;
+
+export const AuditQueries = {
+  list: "audit:query:list",
+} as const;

package/src/audit/feature.ts

@@ -0,0 +1,23 @@
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { listQuery } from "./handlers/list.query";
+
+// Audit feature — exposes a filtered read over the framework's event log.
+//
+// Design: the event-store IS the audit trail (every entity write produces
+// an event with who/when/what/where/delta). This feature adds no persistence,
+// no projection, no cursor — it's a single privileged query handler over
+// the existing `events` table. See handlers/list.query.ts for the filter
+// surface.
+//
+// Retention lives elsewhere. Events are kept indefinitely as the source of
+// truth for state; archive or compress policies are a separate concern
+// (tracked with the snapshot/archive infrastructure that already exists in
+// the framework).
+export function createAuditFeature(): FeatureDefinition {
+  return defineFeature("audit", (r) => {
+    const queries = {
+      list: r.queryHandler(listQuery),
+    };
+    return { queries };
+  });
+}

package/src/audit/handlers/list.query.ts

@@ -0,0 +1,98 @@
+// Audit query — reads the event-store's `events` table directly. The event-
+// log IS the audit trail by construction: every entity write appends at least
+// one event with createdBy (who), createdAt (when), tenantId (where),
+// aggregateType + aggregateId (what), type (action), and payload (delta).
+//
+// No projection, no separate audit table. Queryable with the same filter
+// surface any audit UI needs; tenant-isolated at the WHERE level so cross-
+// tenant peeking is structurally impossible for non-SystemAdmin callers.
+//
+// Sensitive field-values are already stripped out of payloads at event-
+// append time (see event-store-executor → stripSensitive), so this query
+// can't surface PII that the entity definition marked as sensitive.
+
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import { and, desc, eq, gte, lt, lte } from "drizzle-orm";
+import { z } from "zod";
+
+// Per-page cap. 100 keeps a single page payload bounded while being enough
+// for a humans-browse UI — clients that need exports iterate by `before`.
+const MAX_LIMIT = 100;
+
+export const listQuery = defineQueryHandler({
+  name: "list",
+  schema: z
+    .object({
+      // Cursor-style pagination: pass the `id` from the last row of the
+      // previous page as `before`. bigserial ids are monotonic, so `< before`
+      // reliably returns "the next older page". Beats OFFSET on large tables.
+      // The regex pins the input to digits-only — otherwise an invalid value
+      // would surface as a raw PG `invalid_text_representation` instead of a
+      // clean 400 at the schema gate.
+      before: z.string().regex(/^\d+$/, "cursor must be a positive integer").optional(),
+      limit: z.number().int().min(1).max(MAX_LIMIT).default(50),
+      // Filters — all optional. Combined via AND.
+      aggregateType: z.string().optional(),
+      aggregateId: z.uuid().optional(),
+      eventType: z.string().optional(),
+      // createdBy is stored as text on the events table (it accepts both UUIDs
+      // and system actor strings like "SYSTEM"), so the filter is a plain
+      // equality check on the raw value.
+      userId: z.string().optional(),
+      // Inclusive bounds. Clients pass ISO-8601; we parse to Temporal.Instant
+      // and compare via the `instant()` column type.
+      from: z.iso.datetime().optional(),
+      to: z.iso.datetime().optional(),
+    })
+    .refine((v) => !v.from || !v.to || v.from <= v.to, {
+      message: "`from` must be less than or equal to `to`",
+      path: ["from"],
+    }),
+  access: { roles: ["Admin", "SystemAdmin"] },
+  handler: async (query, ctx) => {
+    const p = query.payload;
+    const tenantId = query.user.tenantId;
+
+    const conditions = [eq(eventsTable.tenantId, tenantId)];
+    if (p.aggregateType) conditions.push(eq(eventsTable.aggregateType, p.aggregateType));
+    if (p.aggregateId) conditions.push(eq(eventsTable.aggregateId, p.aggregateId));
+    if (p.eventType) conditions.push(eq(eventsTable.type, p.eventType));
+    if (p.userId) conditions.push(eq(eventsTable.createdBy, p.userId));
+    if (p.from) conditions.push(gte(eventsTable.createdAt, Temporal.Instant.from(p.from)));
+    if (p.to) conditions.push(lte(eventsTable.createdAt, Temporal.Instant.from(p.to)));
+    // `before` = last seen id from the previous page. bigserial so `<` walks
+    // backwards in chronological order. Schema-regex guarantees the string
+    // is digits-only, so BigInt(...) can't throw.
+    if (p.before) conditions.push(lt(eventsTable.id, BigInt(p.before)));
+
+    const rows = await ctx.db
+      .select({
+        id: eventsTable.id,
+        aggregateId: eventsTable.aggregateId,
+        aggregateType: eventsTable.aggregateType,
+        version: eventsTable.version,
+        type: eventsTable.type,
+        payload: eventsTable.payload,
+        metadata: eventsTable.metadata,
+        createdAt: eventsTable.createdAt,
+        createdBy: eventsTable.createdBy,
+      })
+      .from(eventsTable)
+      .where(and(...conditions))
+      .orderBy(desc(eventsTable.id))
+      .limit(p.limit);
+
+    // bigint ids need serialisation — JSON can't carry a plain BigInt, and
+    // clients pass the cursor back as a string via `before`. Stringified once
+    // here so the response shape matches what the caller will re-submit.
+    const serialised = rows.map((r) => ({ ...r, id: String(r["id"]) }));
+    const last = serialised[serialised.length - 1];
+    return {
+      rows: serialised,
+      // Cursor for the NEXT page. Null when this page is partial (we hit
+      // the start of the log) so clients know to stop.
+      nextBefore: serialised.length === p.limit && last ? last["id"] : null,
+    };
+  },
+});

package/src/audit/index.ts

@@ -0,0 +1,2 @@
+export { AUDIT_FEATURE, AuditQueries } from "./constants";
+export { createAuditFeature } from "./feature";