@cosmicdrift/kumiko-bundled-features 0.187.0 → 0.188.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.187.0",
+  "version": "0.188.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>",
@@ -45,6 +45,8 @@
     "./notes-history": "./src/notes-history/index.ts",
     "./notes-history/web": "./src/notes-history/web/index.ts",
     "./notes-history-user-data": "./src/notes-history-user-data/index.ts",
+    "./form-draft": "./src/form-draft/index.ts",
+    "./form-draft-user-data": "./src/form-draft-user-data/index.ts",
     "./template-resolver-user-data": "./src/template-resolver-user-data/index.ts",
     "./folders-user-data": "./src/folders-user-data/index.ts",
     "./ledger": "./src/ledger/index.ts",
@@ -121,12 +123,12 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.187.0",
-    "@cosmicdrift/kumiko-framework": "0.187.0",
-    "@cosmicdrift/kumiko-headless": "0.187.0",
-    "@cosmicdrift/kumiko-renderer": "0.187.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.187.0",
-    "@cosmicdrift/kumiko-types": "0.187.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.188.0",
+    "@cosmicdrift/kumiko-framework": "0.188.0",
+    "@cosmicdrift/kumiko-headless": "0.188.0",
+    "@cosmicdrift/kumiko-renderer": "0.188.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.188.0",
+    "@cosmicdrift/kumiko-types": "0.188.0",
     "@mollie/api-client": "^4.5.0",
     "imapflow": "^1.3.3",
     "mailparser": "^3.9.8",

package/src/billing-foundation/__tests__/billing-foundation.integration.test.ts

@@ -728,7 +728,7 @@ describe("scenario 10: PII is encrypted at rest, not just erasable on destroy",
       subscriptionAggregateId(admin.tenantId),
       admin.tenantId,
     );
-    const ciphertextBefore = (esEventsBefore[0]?.payload as { providerCustomerId?: string })
+    const ciphertextBefore = (esEventsBefore[0]!.payload as { providerCustomerId?: string })
       .providerCustomerId as string;
 
     // This is exactly what tenant-lifecycle's "subject-keys" pipeline stage

package/src/custom-fields/__tests__/retention.integration.test.ts

@@ -210,7 +210,7 @@ describe("T1.5d: per-field retention sweep", () => {
     });
 
     const row = await readRow(propertyId);
-    expect((row?.["custom_fields"] as Record<string, unknown>)["recent"]).toBe("keep-me");
+    expect((row!["custom_fields"] as Record<string, unknown>)["recent"]).toBe("keep-me");
   });
 
   test("field without retention policy: untouched even on ancient rows", async () => {
@@ -233,7 +233,7 @@ describe("T1.5d: per-field retention sweep", () => {
 
     expect(report.rowsUpdated).toBe(0);
     const row = await readRow(propertyId);
-    expect((row?.["custom_fields"] as Record<string, unknown>)["forever"]).toBe("keep-me-always");
+    expect((row!["custom_fields"] as Record<string, unknown>)["forever"]).toBe("keep-me-always");
   });
 
   test("mixed: only expired-with-policy keys are stripped, others stay", async () => {

package/src/form-draft/__tests__/cleanup.integration.test.ts

@@ -0,0 +1,254 @@
+// form-draft cleanup job — real Postgres + real BullMQ dispatch (via
+// stack.jobRunner), no hand-fed context. Covers the #1891 acceptance
+// criteria: an old draft is deleted, a fresh one survives, and the
+// retention window actually comes from the config key (not a hardcoded
+// constant). Also covers #1915: FileRefs in a stale draft's blob are
+// released through the storage provider before the row is deleted, resolved
+// per-row's OWN tenant (not the job's SYSTEM_TENANT_ID run-tenant) — a
+// two-tenant, two-provider setup below proves rows never cross providers.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { randomBytes } from "node:crypto";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createInMemoryFileProvider,
+  fileRefEntity,
+  type InMemoryFileProvider,
+} from "@cosmicdrift/kumiko-framework/files";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createTestEnvelopeCipher, waitFor } from "@cosmicdrift/kumiko-framework/testing";
+import { ConfigHandlers } from "../../config/constants";
+import { createConfigAccessorFactory, createConfigFeature } from "../../config/feature";
+import { createConfigResolver } from "../../config/resolver";
+import { configValuesTable } from "../../config/table";
+import { FormDraftHandlers } from "../constants";
+import { formDraftEntity } from "../entity";
+import { formDraftFeature } from "../feature";
+import { FORM_DRAFT_RETENTION_DAYS_CONFIG_KEY } from "../handlers/cleanup.job";
+
+let stack: TestStack;
+
+const systemAdmin = createTestUser({ id: 1, roles: ["SystemAdmin"] });
+const owner = createTestUser({ id: 2, roles: ["TenantMember"] });
+
+const TENANT_B: TenantId = testTenantId(2);
+const ownerTenantB = createTestUser({ id: 3, roles: ["TenantMember"], tenantId: TENANT_B });
+
+const providerA: InMemoryFileProvider = createInMemoryFileProvider();
+const providerB: InMemoryFileProvider = createInMemoryFileProvider();
+
+beforeAll(async () => {
+  const testEncryptionKey = randomBytes(32).toString("base64");
+  const encryption = createTestEnvelopeCipher(testEncryptionKey);
+  const resolver = createConfigResolver({ cipher: encryption });
+
+  stack = await setupTestStack({
+    features: [formDraftFeature, createConfigFeature()],
+    jobs: {
+      consumerLane: "worker",
+      queueNamePrefix: `kumiko-form-draft-cleanup-test-${Date.now()}`,
+    },
+    extraContext: ({ registry }) => ({
+      configResolver: resolver,
+      configEncryption: encryption,
+      _configAccessorFactory: createConfigAccessorFactory(registry, resolver),
+      // Two providers, keyed by tenant — proves the cleanup job resolves
+      // each stale row's OWN tenant rather than reusing a single
+      // job-level ctx.files (which would be bound to SYSTEM_TENANT_ID, the
+      // tenant this system-wide job actually dispatches under).
+      _fileProviderResolver: (tenantId: TenantId) =>
+        Promise.resolve(tenantId === TENANT_B ? providerB : providerA),
+    }),
+  });
+  await unsafeCreateEntityTable(stack.db, formDraftEntity);
+  await unsafeCreateEntityTable(stack.db, fileRefEntity, "fileRef");
+  await unsafePushTables(stack.db, { configValuesTable });
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  providerA.clear();
+  providerB.clear();
+  await asRawClient(stack.db).unsafe("DELETE FROM kumiko_events");
+  await asRawClient(stack.db).unsafe("DELETE FROM read_form_drafts");
+  await asRawClient(stack.db).unsafe("DELETE FROM read_config_values");
+  await asRawClient(stack.db).unsafe("DELETE FROM file_refs");
+});
+
+async function saveDraft(
+  draftKey: string,
+  values: Record<string, unknown> = { note: "x" },
+  user = owner,
+): Promise<void> {
+  await stack.http.writeOk(FormDraftHandlers.save, { draftKey, values, stepIndex: 0 }, user);
+}
+
+function fileRefPointer(storageKey: string) {
+  return { id: "file-1", storageKey, fileName: "photo.jpg", mimeType: "image/jpeg", size: 3 };
+}
+
+// The real file_refs row a genuine POST /files upload would have created —
+// filterOwnedStorageKeys requires this to exist before a release proceeds.
+async function seedFileRef(storageKey: string, uploader = owner): Promise<void> {
+  await asRawClient(stack.db).unsafe(
+    `INSERT INTO "file_refs" ("tenant_id", "storage_key", "file_name", "mime_type", "size", "inserted_by_id")
+     VALUES ($1, $2, 'photo.jpg', 'image/jpeg', 3, $3)`,
+    [uploader.tenantId, storageKey, uploader.id],
+  );
+}
+
+async function backdate(draftKey: string, daysAgo: number): Promise<void> {
+  await asRawClient(stack.db).unsafe(
+    `UPDATE "read_form_drafts"
+     SET "inserted_at" = now() - ($1::int * interval '1 day'),
+         "modified_at" = now() - ($1::int * interval '1 day')
+     WHERE "draft_key" = $2`,
+    [daysAgo, draftKey],
+  );
+}
+
+async function draftExists(draftKey: string): Promise<boolean> {
+  const rows = await asRawClient(stack.db).unsafe(
+    "SELECT 1 FROM read_form_drafts WHERE draft_key = $1",
+    [draftKey],
+  );
+  return (rows as unknown[]).length > 0;
+}
+
+async function setRetentionDays(days: number): Promise<void> {
+  await stack.http.writeOk(
+    ConfigHandlers.set,
+    { key: FORM_DRAFT_RETENTION_DAYS_CONFIG_KEY, value: days },
+    systemAdmin,
+  );
+}
+
+async function dispatchCleanup(): Promise<void> {
+  if (!stack.jobRunner) throw new Error("jobRunner not wired — check setupTestStack jobs option");
+  await stack.jobRunner.dispatch("form-draft:job:cleanup", {});
+}
+
+describe("form-draft cleanup job", () => {
+  test("deletes a draft older than the default retention window, leaves a fresh one alone", async () => {
+    await saveDraft("wizard:old");
+    await backdate("wizard:old", 31);
+    await saveDraft("wizard:fresh");
+    await dispatchCleanup();
+
+    await waitFor(async () => {
+      expect(await draftExists("wizard:old")).toBe(false);
+    });
+    expect(await draftExists("wizard:fresh")).toBe(true);
+  });
+
+  test("honours a retention window set via the config key", async () => {
+    await setRetentionDays(2);
+    await saveDraft("wizard:stale");
+    await backdate("wizard:stale", 3);
+    await saveDraft("wizard:recent");
+    await backdate("wizard:recent", 1);
+    await dispatchCleanup();
+
+    await waitFor(async () => {
+      expect(await draftExists("wizard:stale")).toBe(false);
+    });
+    expect(await draftExists("wizard:recent")).toBe(true);
+  });
+
+  test("without a configured override, the same 3-day-old draft survives under the 30-day default", async () => {
+    await saveDraft("wizard:three-days-old");
+    await backdate("wizard:three-days-old", 3);
+    await saveDraft("wizard:sentinel");
+    await backdate("wizard:sentinel", 31);
+    await dispatchCleanup();
+
+    // Positive completion signal via the sentinel — proves the run finished
+    // without relying on a fixed sleep, then asserts the config-boundary case.
+    await waitFor(async () => {
+      expect(await draftExists("wizard:sentinel")).toBe(false);
+    });
+    expect(await draftExists("wizard:three-days-old")).toBe(true);
+  });
+});
+
+describe("form-draft cleanup job — FileRef release (#1915)", () => {
+  test("releases FileRefs from a stale draft, leaves a FileRef-less stale draft and a fresh draft unaffected", async () => {
+    const key = "tenant-a/vehicle/photo.jpg";
+    await providerA.write(key, new Uint8Array([1, 2, 3]), "image/jpeg");
+    await seedFileRef(key);
+
+    await saveDraft("wizard:stale-with-photo", { photo: fileRefPointer(key) });
+    await backdate("wizard:stale-with-photo", 31);
+    await saveDraft("wizard:stale-no-photo", { note: "plain" });
+    await backdate("wizard:stale-no-photo", 31);
+    await saveDraft("wizard:fresh", { note: "keep" });
+
+    await dispatchCleanup();
+
+    await waitFor(async () => {
+      expect(await draftExists("wizard:stale-with-photo")).toBe(false);
+    });
+    expect(await draftExists("wizard:stale-no-photo")).toBe(false);
+    expect(await draftExists("wizard:fresh")).toBe(true);
+    expect(providerA.keys()).not.toContain(key);
+  });
+
+  test("resolves each stale row's own tenant provider — never the job's SYSTEM_TENANT_ID run-tenant, never another row's tenant", async () => {
+    const keyA = "tenant-a/vehicle/photo-a.jpg";
+    const keyB = "tenant-b/vehicle/photo-b.jpg";
+    await providerA.write(keyA, new Uint8Array([1]), "image/jpeg");
+    await providerB.write(keyB, new Uint8Array([2]), "image/jpeg");
+    await seedFileRef(keyA, owner);
+    await seedFileRef(keyB, ownerTenantB);
+
+    await saveDraft("wizard:tenant-a-stale", { photo: fileRefPointer(keyA) }, owner);
+    await backdate("wizard:tenant-a-stale", 31);
+    await saveDraft("wizard:tenant-b-stale", { photo: fileRefPointer(keyB) }, ownerTenantB);
+    await backdate("wizard:tenant-b-stale", 31);
+
+    await dispatchCleanup();
+
+    await waitFor(async () => {
+      expect(await draftExists("wizard:tenant-a-stale")).toBe(false);
+    });
+    await waitFor(async () => {
+      expect(await draftExists("wizard:tenant-b-stale")).toBe(false);
+    });
+
+    expect(providerA.keys()).not.toContain(keyA);
+    expect(providerB.keys()).not.toContain(keyB);
+    // Cross-tenant guard: neither key ever lands in the other tenant's provider.
+    expect(providerA.keys()).not.toContain(keyB);
+    expect(providerB.keys()).not.toContain(keyA);
+  });
+
+  test("does NOT release a storageKey with no owned file_refs row (forged draft value)", async () => {
+    const forgedKey = "tenant-a/vehicle/victim.jpg";
+    await providerA.write(forgedKey, new Uint8Array([9, 9, 9]), "image/jpeg");
+    // Deliberately no seedFileRef — the stale draft's `values` claims a
+    // storageKey its owner never actually uploaded.
+
+    await saveDraft("wizard:stale-forged", { photo: fileRefPointer(forgedKey) });
+    await backdate("wizard:stale-forged", 31);
+
+    await dispatchCleanup();
+
+    await waitFor(async () => {
+      expect(await draftExists("wizard:stale-forged")).toBe(false);
+    });
+    expect(providerA.keys()).toContain(forgedKey);
+  });
+});

package/src/form-draft/__tests__/discard-file-refs.integration.test.ts

@@ -0,0 +1,165 @@
+// Discard releases FileRefs held in the draft blob (issue #1915), but ONLY
+// when the caller explicitly opts in via releaseFiles: true, AND only for
+// storageKeys backed by a real file_refs row owned by the caller. A photo
+// upload during a wizard-mode form is written to storage immediately — the
+// draft blob only holds the FileRef pointer ({ id, storageKey, ... }, the
+// shape POST /files returns). render-edit.tsx's only two current call sites
+// both discard right after a *successful* entity submit, which already
+// carries the same storageKeys into the domain entity — releasing
+// unconditionally there would destroy files the entity now depends on.
+// releaseFiles is for an actual abandon/abort flow instead (see schemas.ts).
+//
+// The ownership check matters independently of releaseFiles: `values` is
+// free-form, client-supplied JSON — without verifying a real, owned
+// file_refs row exists, a forged { storageKey: "<victim's key>" } would
+// reach the storage provider's delete() unchecked (see
+// db/queries/owned-file-refs.ts).
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createInMemoryFileProvider,
+  fileRefEntity,
+  type InMemoryFileProvider,
+} from "@cosmicdrift/kumiko-framework/files";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createConfigFeature } from "../../config";
+import { FormDraftHandlers, FormDraftQueries } from "../constants";
+import { formDraftEntity } from "../entity";
+import { formDraftFeature } from "../feature";
+import type { GetDraftResult } from "../handlers/get.query";
+
+let stack: TestStack;
+let provider: InMemoryFileProvider;
+
+const owner = createTestUser({ id: 1, roles: ["TenantMember"] });
+
+beforeAll(async () => {
+  provider = createInMemoryFileProvider();
+  stack = await setupTestStack({
+    features: [formDraftFeature, createConfigFeature()],
+    files: { storageProvider: provider },
+  });
+  await unsafeCreateEntityTable(stack.db, formDraftEntity);
+  await unsafeCreateEntityTable(stack.db, fileRefEntity, "fileRef");
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  provider.clear();
+  await asRawClient(stack.db).unsafe("DELETE FROM kumiko_events");
+  await asRawClient(stack.db).unsafe("DELETE FROM read_form_drafts");
+  await asRawClient(stack.db).unsafe("DELETE FROM file_refs");
+});
+
+async function saveDraft(draftKey: string, values: Record<string, unknown>): Promise<void> {
+  await stack.http.writeOk(FormDraftHandlers.save, { draftKey, values, stepIndex: 0 }, owner);
+}
+
+async function getDraft(draftKey: string): Promise<GetDraftResult> {
+  return stack.http.queryOk<GetDraftResult>(FormDraftQueries.get, { draftKey }, owner);
+}
+
+async function discardDraft(draftKey: string, releaseFiles?: boolean): Promise<unknown> {
+  return stack.http.writeOk(FormDraftHandlers.discard, { draftKey, releaseFiles }, owner);
+}
+
+function fileRefPointer(storageKey: string) {
+  return { id: "file-1", storageKey, fileName: "photo.jpg", mimeType: "image/jpeg", size: 3 };
+}
+
+// The real file_refs row a genuine POST /files upload would have created —
+// filterOwnedStorageKeys requires this to exist before a release proceeds.
+async function seedFileRef(storageKey: string, ownerUser = owner): Promise<void> {
+  await asRawClient(stack.db).unsafe(
+    `INSERT INTO "file_refs" ("tenant_id", "storage_key", "file_name", "mime_type", "size", "inserted_by_id")
+     VALUES ($1, $2, 'photo.jpg', 'image/jpeg', 3, $3)`,
+    [ownerUser.tenantId, storageKey, ownerUser.id],
+  );
+}
+
+describe("form-draft discard — FileRef release", () => {
+  test("discarding with releaseFiles: true and a single-file field releases its storage binary", async () => {
+    const key = "tenant/vehicle/photo/one.jpg";
+    await provider.write(key, new Uint8Array([1, 2, 3]), "image/jpeg");
+    await seedFileRef(key);
+
+    await saveDraft("wizard:one-photo", { photo: fileRefPointer(key) });
+    expect(provider.keys()).toContain(key);
+
+    await discardDraft("wizard:one-photo", true);
+
+    expect(provider.keys()).not.toContain(key);
+    expect((await getDraft("wizard:one-photo")).draft).toBeNull();
+  });
+
+  test("discarding with releaseFiles: true and a multi-file field releases every storage binary", async () => {
+    const keyA = "tenant/vehicle/photos/a.jpg";
+    const keyB = "tenant/vehicle/photos/b.jpg";
+    await provider.write(keyA, new Uint8Array([1]), "image/jpeg");
+    await provider.write(keyB, new Uint8Array([2]), "image/jpeg");
+    await seedFileRef(keyA);
+    await seedFileRef(keyB);
+
+    await saveDraft("wizard:many-photos", {
+      photos: [fileRefPointer(keyA), fileRefPointer(keyB)],
+    });
+
+    await discardDraft("wizard:many-photos", true);
+
+    expect(provider.keys()).not.toContain(keyA);
+    expect(provider.keys()).not.toContain(keyB);
+  });
+
+  test("discarding without releaseFiles leaves the storage binary intact (successful-submit default)", async () => {
+    const key = "tenant/vehicle/photo/kept.jpg";
+    await provider.write(key, new Uint8Array([1, 2, 3]), "image/jpeg");
+    await seedFileRef(key);
+
+    await saveDraft("wizard:submitted", { photo: fileRefPointer(key) });
+    await discardDraft("wizard:submitted");
+
+    expect(provider.keys()).toContain(key);
+    expect((await getDraft("wizard:submitted")).draft).toBeNull();
+  });
+
+  test("discarding with releaseFiles: true does NOT release a storageKey with no owned file_refs row", async () => {
+    const forgedKey = "tenant/vehicle/photo/victim.jpg";
+    await provider.write(forgedKey, new Uint8Array([9, 9, 9]), "image/jpeg");
+    // Deliberately no seedFileRef(forgedKey) — the draft's `values` claims a
+    // storageKey the caller never actually uploaded (e.g. a guessed/leaked
+    // key belonging to another user's real upload).
+
+    await saveDraft("wizard:forged-pointer", { photo: fileRefPointer(forgedKey) });
+    await discardDraft("wizard:forged-pointer", true);
+
+    expect(provider.keys()).toContain(forgedKey);
+  });
+
+  test("discarding a draft without any FileRefs completes without error", async () => {
+    await saveDraft("wizard:text-only", { note: "no photos here" });
+
+    await discardDraft("wizard:text-only", true);
+
+    expect((await getDraft("wizard:text-only")).draft).toBeNull();
+  });
+
+  test("discarding a draftKey that was never saved is a no-op and touches no storage", async () => {
+    const key = "tenant/vehicle/photo/untouched.jpg";
+    await provider.write(key, new Uint8Array([1]), "image/jpeg");
+
+    await expect(discardDraft("wizard:never-saved", true)).resolves.toBeTruthy();
+
+    expect(provider.keys()).toContain(key);
+  });
+});