@cosmicdrift/kumiko-samples 0.361.0 → 0.362.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.361.0",
+  "version": "0.362.0",
   "description": "Source trees of the Kumiko sample recipes, sample apps and bundled features in repo layout, for tooling such as few-shot corpus builds.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.361.0",
+  "version": "0.362.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>",

package/packages/bundled-features/src/document-ingest-foundation/aggregate-id.ts

@@ -0,0 +1,10 @@
+import { v5 as uuidv5 } from "uuid";
+
+// Fixed UUID namespace for document-ingest stream derivation. Frozen: changing
+// it re-keys every existing ingest stream.
+const DOCUMENT_INGEST_NAMESPACE = "5c1e8b7a-3d94-4f2a-b6e0-9a7d1c4f8e23";
+
+// @wrapper-known uuid-domain
+export function documentIngestAggregateId(tenantId: string, fileRefId: string): string {
+  return uuidv5(`${tenantId}|${fileRefId}`, DOCUMENT_INGEST_NAMESPACE);
+}

package/packages/bundled-features/src/document-ingest-foundation/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.362.0",
+    "type": "fix",
+    "title": "document-ingest events live on their own stream",
+    "detail": "documentIngest.requested/skipped were appended to the fileRef's own event stream (aggregateId = fileRefId), so the request-ingest projection racing a save that binds a pending upload broke the fileRef's optimistic lock (409 version_conflict). They now use documentIngestAggregateId(tenantId, fileRefId); payload.fileRefId is unchanged."
+  },
   {
     "version": "0.335.0",
     "type": "fix",

package/packages/bundled-features/src/document-ingest-foundation/events.ts

@@ -1,7 +1,9 @@
 import * as z from "zod";
 
 // documentIngest — own aggregate-type for the ingest-request stream, one
-// stream per fileRef (aggregateId = fileRefId). Not backed by an r.entity;
+// stream per fileRef with aggregateId derived from the fileRefId
+// (documentIngestAggregateId), never the fileRefId itself: foreign events on
+// the fileRef stream would break the fileRef's optimistic lock. Not backed by an r.entity;
 // this is a pure saga-anchor event (kumiko-framework#1497) that the Phase-2
 // worker job (kumiko-enterprise LiteParse provider) subscribes to.
 export const DOCUMENT_INGEST_AGGREGATE_TYPE = "document-ingest";

package/packages/bundled-features/src/document-ingest-foundation/feature.ts

@@ -14,6 +14,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { normalizeMimeType } from "@cosmicdrift/kumiko-framework/files";
 import * as z from "zod";
+import { documentIngestAggregateId } from "./aggregate-id.js";
 import { validateDocumentIngestProviderWiring } from "./boot-checks.js";
 import { documentExtractEntity } from "./entity.js";
 import {
@@ -66,13 +67,14 @@ type FileRefIngestFields = z.infer<typeof fileRefIngestFieldsSchema>;
 // delete→restore round-trip re-requests ingest instead of leaving the file
 // without an extract.
 async function requestIngestForFileRef(
-  event: { readonly aggregateId: string },
+  event: { readonly aggregateId: string; readonly tenantId: string },
   fileRef: FileRefIngestFields,
   ctx: MspApplyContext,
 ): Promise<void> {
+  const ingestAggregateId = documentIngestAggregateId(event.tenantId, event.aggregateId);
   const skip = (reason: "file-too-large" | "unsupported-mime-type") =>
     ctx.unsafeAppendEvent({
-      aggregateId: event.aggregateId,
+      aggregateId: ingestAggregateId,
       aggregateType: DOCUMENT_INGEST_AGGREGATE_TYPE,
       type: DOCUMENT_INGEST_SKIPPED_EVENT_QN,
       payload: {
@@ -105,7 +107,7 @@ async function requestIngestForFileRef(
   }
 
   await ctx.unsafeAppendEvent({
-    aggregateId: event.aggregateId,
+    aggregateId: ingestAggregateId,
     aggregateType: DOCUMENT_INGEST_AGGREGATE_TYPE,
     type: DOCUMENT_INGEST_REQUESTED_EVENT_QN,
     payload: {

package/packages/bundled-features/src/document-ingest-foundation/index.ts

@@ -1,5 +1,6 @@
 // Public API of the document-ingest-foundation bundled-feature.
 
+export { documentIngestAggregateId } from "./aggregate-id.js";
 export {
   type DocumentExtractMeta,
   documentExtractEntity,

package/packages/bundled-features/src/user-data-rights/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.362.0",
+    "type": "fix",
+    "title": "download-attempt.ip and userAgent are encrypted personal data instead of plaintext",
+    "detail": "download-attempt.ip and userAgent are declared personal: { of: \"attemptedByUserId\", whenAbsent: \"tenant\" }, ip with find \"exact\" and userAgent with find \"none\". With a KMS configured, rows written by the logged-in job path are encrypted under the requesting user's key (a user forget makes IP and user agent unreadable), rows from the anonymous token path under the tenant key. The new ip_bidx column keeps the equality filter of list-download-attempts working across both kinds of rows, and the query now returns the decrypted values (an erased user's values come back as the erased sentinel). user-data-rights-defaults registers an EXT_USER_DATA hook for download-attempt: export lists the user's own attempts, delete purges the user's own attempts via the forget verb (projection row and blind index included, replayed on rebuild); owner-less token-path rows expire with the 90d hardDelete retention.",
+    "migration": "Apps that mount user-data-rights run kumiko-schema generate and apply: the migration adds the ip_bidx column and its index to read_download_attempts. Apps that mount user-data-rights without user-data-rights-defaults must register their own EXT_USER_DATA hook for the download-attempt entity, otherwise boot fails the PII hook coverage check. The annotation fingerprint of the boot PII backfill changes, so the first boot after the bump does one full pass: it encrypts existing download-attempt events (tenant key or user key) and rebuilds the projection including ip_bidx (KUMIKO_SKIP_PII_BACKFILL=1 turns it off)."
+  },
   {
     "version": "0.354.0",
     "type": "breaking",

package/packages/bundled-features/src/user-data-rights/handlers/download-by-token.query.ts

@@ -76,7 +76,11 @@ export const downloadByTokenQuery = defineQueryHandler({
       })
       .optional(),
   }),
-  access: { roles: ["anonymous", "Member", "User", "TenantAdmin", "SystemAdmin"] },
+  // public-intake: rejected attempts store the anonymous caller's IP in the audit row.
+  access: {
+    roles: ["anonymous", "Member", "User", "TenantAdmin", "SystemAdmin"],
+    personalData: "public-intake",
+  },
   agent: { expose: false },
   // Brute-Force-Schutz fuer Token-Hash-Probing. Anonymous-Endpoint mit
   // 32-byte-Random-Token = 256 Bit Search-Space, aber rate-limit als

package/packages/bundled-features/src/user-data-rights/handlers/list-download-attempts.query.ts

@@ -2,12 +2,14 @@ import { selectMany, type WhereObject } from "@cosmicdrift/kumiko-framework/bun-
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import * as z from "zod";
+import { decryptStoredPii } from "../../shared/index.js";
 import { downloadAttemptsTable } from "../schema/download-attempt.js";
 
 // Operator-Query: invalid Download-Attempts (S2.U7).
 // DPO-Sicht fuer Brute-Force-Detection. Tenant-isolated via WHERE.
 
 const MAX_LIMIT = 100;
+const REQUEST_ID = "user-data-rights:list-download-attempts";
 
 export const listDownloadAttemptsQuery = defineQueryHandler({
   name: "list-download-attempts",
@@ -44,6 +46,16 @@ export const listDownloadAttemptsQuery = defineQueryHandler({
       limit: p.limit,
     });
 
-    return { rows };
+    const decryptedRows = await Promise.all(
+      rows.map(async (row) => ({
+        ...row,
+        ip: row.ip === null ? null : await decryptStoredPii(row.ip, "ip", REQUEST_ID),
+        userAgent:
+          row.userAgent === null
+            ? null
+            : await decryptStoredPii(row.userAgent, "userAgent", REQUEST_ID),
+      })),
+    );
+    return { rows: decryptedRows };
   },
 });

package/packages/bundled-features/src/user-data-rights/index.ts

@@ -25,6 +25,7 @@ export type { SendDeletionExecutedEmailFn } from "./run-forget-cleanup.js";
 export { policyToStrategy, runForgetCleanup } from "./run-forget-cleanup.js";
 export type { UserExportBundle } from "./run-user-export.js";
 export { runUserExport } from "./run-user-export.js";
+export { downloadAttemptEntity, downloadAttemptsTable } from "./schema/download-attempt.js";
 export {
   ACTIVE_JOB_CONSTRAINT,
   EXPORT_JOB_STATUS,

package/packages/bundled-features/src/user-data-rights/schema/download-attempt.ts

@@ -35,23 +35,17 @@ export const downloadAttemptEntity = createEntity({
     jobId: createTextField({ personal: false, reason: "technical_reference" }),
     // User-ID wenn auth-Pfad (job). NULL bei anonymous (token-Pfad).
     attemptedByUserId: createTextField({ personal: false, reason: "pseudonymous_fk" }),
-    // No subject annotation on this buildEntityTable-managed entity:
-    // attemptedByUserId is null-by-design for the anonymous token path, so
-    // `personal: { of: "attemptedByUserId" }` would throw SubjectResolutionError
-    // on every such row once a KMS is configured
-    // (crypto/subject-resolver.ts resolveUserOwnedSubject).
-    // The job path knows the requester and an IP is personal data, so this is a
-    // deliberate waiver, not business data: a user forget does not shred these
-    // values, the 90d hardDelete below is what removes them.
+    // The anonymous token path has no owner, so those rows fall back to the tenant key;
+    // find "exact" on ip because list-download-attempts filters by IP.
     ip: createTextField({
       maxLength: 64,
-      personal: false,
-      reason: "security_audit_retention_bounded",
+      personal: { of: "attemptedByUserId", whenAbsent: "tenant" },
+      find: "exact",
     }),
     userAgent: createTextField({
       maxLength: 256,
-      personal: false,
-      reason: "security_audit_retention_bounded",
+      personal: { of: "attemptedByUserId", whenAbsent: "tenant" },
+      find: "none",
     }),
     attemptedAt: createTimestampField({ required: true }),
   },

package/packages/bundled-features/src/user-data-rights-defaults/feature.ts

@@ -12,6 +12,10 @@ import {
   deliveryAttemptDeleteHook,
   deliveryAttemptExportHook,
 } from "./hooks/delivery-attempt.userdata-hook.js";
+import {
+  downloadAttemptDeleteHook,
+  downloadAttemptExportHook,
+} from "./hooks/download-attempt.userdata-hook.js";
 import { fileRefDeleteHook, fileRefExportHook } from "./hooks/file-ref.userdata-hook.js";
 import {
   inAppMessageDeleteHook,
@@ -57,7 +61,7 @@ import {
 export function createUserDataRightsDefaultsFeature(): FeatureDefinition {
   return defineFeature("user-data-rights-defaults", (r) => {
     r.describe(
-      "Registers ready-made `EXT_USER_DATA` export and delete hooks for the bundled entities that hold per-user data: `user` (delete strategy sets email to `deleted-<id>@anonymized.invalid`, nulls `passwordHash`, sets status to `Deleted`; anonymize strategy sets email to `anonymized-<id>@anonymized.invalid` without touching `passwordHash`), `fileRef` (delete removes both the DB row and the storage binary), plus — gated on the source feature being mounted — `user-session` (ip/userAgent, hard-delete), `api-token` (hard-delete = revoke), `in-app-message` (hard-delete), `tenant-invitation` (invitee email forgotten/pseudonymized, inviter link severed), `notification-preference` and user-scoped `config-value` (purged via the forget verb), plus export-only hooks for the events-only aggregates `delivery-attempt` (recipientAddress) and `job-run` (payload) whose erasure runs via crypto-shredding. Mount this alongside `user-data-rights` for standard GDPR compliance; omit it only if your app needs custom anonymization logic for these entities.",
+      "Registers ready-made `EXT_USER_DATA` export and delete hooks for the bundled entities that hold per-user data: `user` (delete strategy sets email to `deleted-<id>@anonymized.invalid`, nulls `passwordHash`, sets status to `Deleted`; anonymize strategy sets email to `anonymized-<id>@anonymized.invalid` without touching `passwordHash`), `fileRef` (delete removes both the DB row and the storage binary), plus — gated on the source feature being mounted — `user-session` (ip/userAgent, hard-delete), `api-token` (hard-delete = revoke), `in-app-message` (hard-delete), `tenant-invitation` (invitee email forgotten/pseudonymized, inviter link severed), `notification-preference` and user-scoped `config-value` (purged via the forget verb), plus export-only hooks for the events-only aggregates `delivery-attempt` (recipientAddress) and `job-run` (payload) whose erasure runs via crypto-shredding, and `download-attempt` (rejected export-download attempts of the user: result, path, source IP, user agent, time; delete purges the user's own attempts via the forget verb, token-path rows without an owner expire by retention). Mount this alongside `user-data-rights` for standard GDPR compliance; omit it only if your app needs custom anonymization logic for these entities.",
     );
     r.uiHints({
       displayLabel: "User Data Rights · Default Hooks",
@@ -128,6 +132,11 @@ export function createUserDataRightsDefaultsFeature(): FeatureDefinition {
       delete: deliveryAttemptDeleteHook,
     });
 
+    r.useExtension(EXT_USER_DATA, "download-attempt", {
+      export: downloadAttemptExportHook,
+      delete: downloadAttemptDeleteHook,
+    });
+
     r.useExtension(EXT_USER_DATA, "job-run", {
       export: jobRunExportHook,
       delete: jobRunDeleteHook,

package/packages/bundled-features/src/user-data-rights-defaults/hooks/download-attempt.userdata-hook.ts

@@ -0,0 +1,58 @@
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createSystemUser,
+  type UserDataDeleteHook,
+  type UserDataExportHook,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { collectErasureFailure, throwIfErasureFailed } from "../../shared/index.js";
+import { downloadAttemptEntity, downloadAttemptsTable } from "../../user-data-rights/index.js";
+
+// Event-sourced entity: forget goes through the executor so the erasure replays
+// on rebuild and removes the projection row including ip_bidx.
+const crud = createEventStoreExecutor(downloadAttemptsTable, downloadAttemptEntity, {
+  entityName: "download-attempt",
+});
+
+// Only job-path attempts name a user; token-path rows have no owner and sit
+// under the tenant key. ip may be ciphertext (kumiko-pii:), which the export
+// runner's central decrypt sweep resolves.
+export const downloadAttemptExportHook: UserDataExportHook = async (ctx) => {
+  const rows = await ctx.db.selectMany<Record<string, unknown>>(downloadAttemptsTable, {
+    tenantId: ctx.tenantId,
+    attemptedByUserId: ctx.userId,
+  });
+  if (rows.length === 0) return null;
+  return {
+    entity: "download-attempt",
+    rows: rows.map((r) => ({
+      result: r["result"],
+      via: r["via"],
+      ip: r["ip"],
+      userAgent: r["userAgent"],
+      attemptedAt: r["attemptedAt"],
+    })),
+  };
+};
+
+// Both strategies purge: key erasure alone leaves attemptedByUserId and the
+// blind index linking the user to the row until retention, and not every forget
+// path shreds the subject key.
+export const downloadAttemptDeleteHook: UserDataDeleteHook = async (ctx) => {
+  const systemUser = createSystemUser(ctx.tenantId);
+  const rows = await ctx.db.selectMany<Record<string, unknown>>(downloadAttemptsTable, {
+    tenantId: ctx.tenantId,
+    attemptedByUserId: ctx.userId,
+  });
+  const failures: string[] = [];
+  for (const row of rows) {
+    const id = row["id"];
+    if (typeof id !== "string") continue;
+    collectErasureFailure(
+      await crud.forget({ id }, systemUser, ctx.db),
+      "download-attempt",
+      id,
+      failures,
+    );
+  }
+  throwIfErasureFailed(failures);
+};

package/samples/apps/ui-walkthrough/src/features/rental/screens.ts

@@ -467,7 +467,7 @@ export const leaseDetailGapsScreen: ProjectionDetailScreenDefinition = {
     {
       kind: "writeHandler",
       id: "terminate",
-      icon: "x",
+      icon: "circle-stop",
       label: "rental.action.terminate",
       handler: RENTAL_WRITES.leaseTerminate,
       payload: { pick: ["id"] },

package/samples/apps/use-all-bundled/feature-manifest.json

@@ -1143,7 +1143,9 @@
       "extensionsUsed": [],
       "configKeys": [],
       "secrets": [],
-      "writeHandlers": [],
+      "writeHandlers": [
+        "files:write:bind-referenced-files"
+      ],
       "uiHints": {
         "displayLabel": "Files · Metadata",
         "category": "storage",
@@ -3008,7 +3010,7 @@
     },
     {
       "name": "user-data-rights-defaults",
-      "description": "Registers ready-made `EXT_USER_DATA` export and delete hooks for the bundled entities that hold per-user data: `user` (delete strategy sets email to `deleted-<id>@anonymized.invalid`, nulls `passwordHash`, sets status to `Deleted`; anonymize strategy sets email to `anonymized-<id>@anonymized.invalid` without touching `passwordHash`), `fileRef` (delete removes both the DB row and the storage binary), plus — gated on the source feature being mounted — `user-session` (ip/userAgent, hard-delete), `api-token` (hard-delete = revoke), `in-app-message` (hard-delete), `tenant-invitation` (invitee email forgotten/pseudonymized, inviter link severed), `notification-preference` and user-scoped `config-value` (purged via the forget verb), plus export-only hooks for the events-only aggregates `delivery-attempt` (recipientAddress) and `job-run` (payload) whose erasure runs via crypto-shredding. Mount this alongside `user-data-rights` for standard GDPR compliance; omit it only if your app needs custom anonymization logic for these entities.",
+      "description": "Registers ready-made `EXT_USER_DATA` export and delete hooks for the bundled entities that hold per-user data: `user` (delete strategy sets email to `deleted-<id>@anonymized.invalid`, nulls `passwordHash`, sets status to `Deleted`; anonymize strategy sets email to `anonymized-<id>@anonymized.invalid` without touching `passwordHash`), `fileRef` (delete removes both the DB row and the storage binary), plus — gated on the source feature being mounted — `user-session` (ip/userAgent, hard-delete), `api-token` (hard-delete = revoke), `in-app-message` (hard-delete), `tenant-invitation` (invitee email forgotten/pseudonymized, inviter link severed), `notification-preference` and user-scoped `config-value` (purged via the forget verb), plus export-only hooks for the events-only aggregates `delivery-attempt` (recipientAddress) and `job-run` (payload) whose erasure runs via crypto-shredding, and `download-attempt` (rejected export-download attempts of the user: result, path, source IP, user agent, time; delete purges the user's own attempts via the forget verb, token-path rows without an owner expire by retention). Mount this alongside `user-data-rights` for standard GDPR compliance; omit it only if your app needs custom anonymization logic for these entities.",
       "toggleableDefault": null,
       "requires": [
         "user",
@@ -3064,6 +3066,10 @@
           "extensionName": "userData",
           "entityName": "delivery-attempt"
         },
+        {
+          "extensionName": "userData",
+          "entityName": "download-attempt"
+        },
         {
           "extensionName": "userData",
           "entityName": "job-run"

package/samples/apps/use-all-bundled/kumiko/migrations/0044_download-attempt-ip-bidx.rebuild.json

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "tables": ["read_download_attempts"]
+}