@cosmicdrift/kumiko-bundled-features 0.2.1 → 0.2.3

package/src/user-data-rights/__tests__/run-user-export.integration.ts

@@ -0,0 +1,291 @@
+// User-Data-Export Integration-Test (S2.U3).
+//
+// User-Explicit-Anforderung "alle daten enthalten, ES + files; PII
+// check in daten; alle wichtigen cross data matrix checks".
+//
+// Pinst:
+//   - Bundle enthaelt user-Profil + fileRefs aller Tenant-Memberships
+//     (Cross-Tenant zusammengefuehrt in einem Output).
+//   - PII-Surface: passwordHash + roles + status sind NICHT im Bundle
+//     (User-Hook-Selektion).
+//   - File-Binaries kommen NICHT inline — nur Stueckliste mit
+//     storageKey + fileName (ZIP-Bau ist optional Async-Wrap).
+//   - Other-User-Isolation: Bobs Files nicht in Alices Bundle.
+//   - Orphan-User (0 Memberships): user-Profil-Hook laeuft trotzdem
+//     ueber Pseudo-Tenant.
+
+import {
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import { sql } from "drizzle-orm";
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
+import { createComplianceProfilesFeature } from "../../compliance-profiles";
+import { createDataRetentionFeature } from "../../data-retention";
+import { createFilesFeature } from "../../files";
+import { createUserFeature, USER_STATUS, userEntity, userTable } from "../../user";
+import { createUserDataRightsDefaultsFeature } from "../../user-data-rights-defaults";
+import { createUserDataRightsFeature } from "../feature";
+import { runUserExport } from "../run-user-export";
+
+let stack: TestStack;
+
+const TENANT_A = "00000000-0000-4000-8000-00000000000a";
+const TENANT_B = "00000000-0000-4000-8000-00000000000b";
+const TENANT_SYSTEM = "00000000-0000-4000-8000-000000000001";
+
+function uuid(suffix: number): string {
+  return `bbbbbbbb-bbbb-4bbb-8bbb-${suffix.toString(16).padStart(12, "0")}`;
+}
+
+const ALICE_ID = uuid(1);
+const BOB_ID = uuid(2);
+const ORPHAN_ID = uuid(3);
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [
+      createUserFeature(),
+      createFilesFeature(),
+      createDataRetentionFeature(),
+      createComplianceProfilesFeature(),
+      createUserDataRightsFeature(),
+      createUserDataRightsDefaultsFeature(),
+    ],
+  });
+
+  await unsafeCreateEntityTable(stack.db, userEntity);
+  await stack.db.execute(sql`
+    CREATE TABLE IF NOT EXISTS read_tenant_memberships (
+      id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+      tenant_id UUID NOT NULL,
+      user_id TEXT NOT NULL,
+      version INTEGER NOT NULL DEFAULT 0,
+      inserted_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+      modified_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+      inserted_by_id TEXT,
+      modified_by_id TEXT,
+      is_deleted BOOLEAN NOT NULL DEFAULT false,
+      deleted_at TIMESTAMPTZ,
+      deleted_by_id TEXT,
+      roles TEXT NOT NULL DEFAULT '[]',
+      UNIQUE(user_id, tenant_id)
+    )
+  `);
+  await stack.db.execute(sql`
+    CREATE TABLE IF NOT EXISTS file_refs (
+      id UUID PRIMARY KEY,
+      tenant_id UUID NOT NULL,
+      storage_key TEXT NOT NULL,
+      file_name TEXT NOT NULL,
+      mime_type TEXT NOT NULL,
+      size INTEGER NOT NULL,
+      entity_type TEXT,
+      entity_id TEXT,
+      field_name TEXT,
+      inserted_at TIMESTAMPTZ DEFAULT now() NOT NULL,
+      inserted_by_id TEXT
+    )
+  `);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await stack.db.delete(userTable);
+  await stack.db.execute(sql`DELETE FROM read_tenant_memberships`);
+  await stack.db.execute(sql`DELETE FROM file_refs`);
+});
+
+const NOW = () => getTemporal().Now.instant();
+
+async function seedUser(
+  id: string,
+  overrides: { email?: string; displayName?: string; roles?: string } = {},
+): Promise<void> {
+  await stack.db.insert(userTable).values({
+    id,
+    tenantId: TENANT_SYSTEM,
+    email: overrides.email ?? `user-${id}@example.com`,
+    passwordHash: "secret-hash-must-not-leak",
+    displayName: overrides.displayName ?? `User ${id}`,
+    locale: "de",
+    emailVerified: true,
+    roles: overrides.roles ?? '["Member","SecretRole"]',
+    status: USER_STATUS.Active,
+  });
+}
+
+async function seedMembership(userId: string, tenantId: string): Promise<void> {
+  await stack.db.execute(sql`
+    INSERT INTO read_tenant_memberships (tenant_id, user_id, roles)
+    VALUES (${tenantId}, ${userId}, '["Member"]')
+    ON CONFLICT (user_id, tenant_id) DO NOTHING
+  `);
+}
+
+async function seedFileRef(
+  id: string,
+  tenantId: string,
+  insertedById: string | null,
+  fileName: string,
+): Promise<void> {
+  await stack.db.execute(sql`
+    INSERT INTO file_refs (id, tenant_id, storage_key, file_name, mime_type, size, inserted_by_id)
+    VALUES (${id}, ${tenantId}, ${`storage/${id}`}, ${fileName}, 'application/pdf', 1024, ${insertedById})
+    ON CONFLICT (id) DO NOTHING
+  `);
+}
+
+describe("runUserExport :: alle Daten enthalten + Cross-Tenant", () => {
+  test("Alice in Tenant A + B → Bundle hat user-Profil + fileRefs aus beiden Tenants", async () => {
+    await seedUser(ALICE_ID, {
+      email: "alice@example.com",
+      displayName: "Alice Test",
+    });
+    await seedMembership(ALICE_ID, TENANT_A);
+    await seedMembership(ALICE_ID, TENANT_B);
+    await seedFileRef(uuid(101), TENANT_A, ALICE_ID, "alice-a-1.pdf");
+    await seedFileRef(uuid(102), TENANT_A, ALICE_ID, "alice-a-2.pdf");
+    await seedFileRef(uuid(103), TENANT_B, ALICE_ID, "alice-b-1.pdf");
+
+    const bundle = await runUserExport({
+      db: stack.db,
+      registry: stack.registry,
+      userId: ALICE_ID,
+      now: NOW(),
+    });
+
+    expect(bundle.userId).toBe(ALICE_ID);
+    expect(bundle.tenants).toHaveLength(2);
+
+    // user-Entity in beiden Tenant-Sections (Hook ist tenant-agnostisch
+    // und liefert dasselbe Profil — das ist OK fuer den export-pfad,
+    // App-Author kann Bundle pro Tenant trennen wenn gewuenscht).
+    const tenantA = bundle.tenants.find((t) => t.tenantId === TENANT_A);
+    expect(tenantA).toBeDefined();
+    const userSnippet = tenantA?.entities.find((e) => e.entity === "user");
+    expect(userSnippet).toBeDefined();
+    expect(userSnippet?.rows).toHaveLength(1);
+    expect(String(userSnippet?.rows[0]?.["email"])).toBe("alice@example.com");
+    expect(String(userSnippet?.rows[0]?.["displayName"])).toBe("Alice Test");
+
+    // fileRefs cross-tenant: 2 in A, 1 in B → 4 Snippet-Eintraege
+    // (2× user + 2× fileRef-Entries) und Flat-fileRefs hat 4 Eintraege
+    // total (2 in A + 1 in B = 3 ist falsch — die fileRef-Hook listet
+    // pro Tenant → also 2 + 1 = 3 fileRefs flat).
+    expect(bundle.fileRefs).toHaveLength(3);
+    const fileNamesA = bundle.fileRefs
+      .filter((f) => f.tenantId === TENANT_A)
+      .map((f) => f.fileName);
+    expect(fileNamesA).toContain("alice-a-1.pdf");
+    expect(fileNamesA).toContain("alice-a-2.pdf");
+    const fileNamesB = bundle.fileRefs
+      .filter((f) => f.tenantId === TENANT_B)
+      .map((f) => f.fileName);
+    expect(fileNamesB).toContain("alice-b-1.pdf");
+  });
+});
+
+describe("runUserExport :: PII-Surface (Datenschutz-Audit)", () => {
+  test("Bundle enthaelt KEIN passwordHash + KEIN roles + KEIN status", async () => {
+    await seedUser(ALICE_ID, {
+      roles: '["Member","SecretAdmin","HiddenRole"]',
+    });
+    await seedMembership(ALICE_ID, TENANT_A);
+
+    const bundle = await runUserExport({
+      db: stack.db,
+      registry: stack.registry,
+      userId: ALICE_ID,
+      now: NOW(),
+    });
+
+    // Roundtrip durch JSON.stringify — auch wenn ein Hook das Feld
+    // versehentlich exposed, faellt es hier auf.
+    const serialized = JSON.stringify(bundle);
+    expect(serialized).not.toContain("secret-hash-must-not-leak");
+    expect(serialized).not.toContain("SecretAdmin");
+    expect(serialized).not.toContain("HiddenRole");
+
+    // Strukturell pruefen: user-Profil-Row hat keine privileged-Felder.
+    const userSnippet = bundle.tenants[0]?.entities.find((e) => e.entity === "user");
+    const profile = userSnippet?.rows[0];
+    expect(profile?.["passwordHash"]).toBeUndefined();
+    expect(profile?.["roles"]).toBeUndefined();
+    expect(profile?.["status"]).toBeUndefined();
+  });
+});
+
+describe("runUserExport :: Cross-User-Isolation", () => {
+  test("Alice's Bundle enthaelt KEINE Daten von Bob (gleicher Tenant, andere insertedById)", async () => {
+    await seedUser(ALICE_ID, { email: "alice@example.com" });
+    await seedUser(BOB_ID, { email: "bob.distinct@example.com" });
+    await seedMembership(ALICE_ID, TENANT_A);
+    await seedMembership(BOB_ID, TENANT_A);
+    // Beide haben Files im selben Tenant.
+    await seedFileRef(uuid(201), TENANT_A, ALICE_ID, "alice-private.pdf");
+    await seedFileRef(uuid(202), TENANT_A, BOB_ID, "bob-private.pdf");
+
+    const aliceBundle = await runUserExport({
+      db: stack.db,
+      registry: stack.registry,
+      userId: ALICE_ID,
+      now: NOW(),
+    });
+
+    const aliceFileNames = aliceBundle.fileRefs.map((f) => f.fileName);
+    expect(aliceFileNames).toContain("alice-private.pdf");
+    expect(aliceFileNames).not.toContain("bob-private.pdf");
+
+    // user-Profil enthaelt ALICE's email, nicht Bobs.
+    const userRow = aliceBundle.tenants[0]?.entities.find((e) => e.entity === "user")?.rows[0];
+    expect(String(userRow?.["email"])).toBe("alice@example.com");
+    expect(JSON.stringify(aliceBundle)).not.toContain("bob.distinct@example.com");
+  });
+});
+
+describe("runUserExport :: Orphan-User (0 Memberships)", () => {
+  test("User ohne Memberships → user-Profil trotzdem im Bundle (Pseudo-Tenant)", async () => {
+    await seedUser(ORPHAN_ID, { email: "orphan@example.com" });
+    // KEINE seedMembership.
+
+    const bundle = await runUserExport({
+      db: stack.db,
+      registry: stack.registry,
+      userId: ORPHAN_ID,
+      now: NOW(),
+    });
+
+    expect(bundle.tenants).toHaveLength(1);
+    const orphanSection = bundle.tenants[0];
+    const userSnippet = orphanSection?.entities.find((e) => e.entity === "user");
+    expect(userSnippet?.rows).toHaveLength(1);
+    expect(String(userSnippet?.rows[0]?.["email"])).toBe("orphan@example.com");
+  });
+});
+
+describe("runUserExport :: Empty-State", () => {
+  test("User existiert nicht → leeres Bundle ohne Error", async () => {
+    // KEIN seedUser — der user-Hook returnt null wenn nichts da ist.
+    const bundle = await runUserExport({
+      db: stack.db,
+      registry: stack.registry,
+      userId: ORPHAN_ID,
+      now: NOW(),
+    });
+
+    // Orphan-Path laeuft trotzdem (Hook returnt null → kein Snippet).
+    expect(bundle.userId).toBe(ORPHAN_ID);
+    expect(bundle.fileRefs).toEqual([]);
+    // Der user-Hook gibt `null` zurueck → keine entities-Section.
+    const allUserSnippets = bundle.tenants.flatMap((t) =>
+      t.entities.filter((e) => e.entity === "user"),
+    );
+    expect(allUserSnippets).toEqual([]);
+  });
+});

package/src/user-data-rights/__tests__/token-helpers.test.ts

@@ -0,0 +1,63 @@
+// Token-Helper Unit-Tests (S2.U3 Atom 4a).
+//
+// Pinst:
+//   - generateDownloadToken: 32-byte random → base64url plain + SHA256 hash
+//   - hashDownloadToken: deterministisch (verify-Pfad fuer Atom 4b)
+//   - Web-Crypto-Universal: laeuft in vitest (= bun-runtime via vitest)
+//     ohne node:crypto-Import. Memory `feedback_universal_deps`.
+
+import { describe, expect, test } from "vitest";
+import { generateDownloadToken, hashDownloadToken } from "../token-helpers";
+
+describe("generateDownloadToken", () => {
+  test("returns plain (base64url) + matching hash (hex)", async () => {
+    const { plain, hash } = await generateDownloadToken();
+
+    // base64url-Format: 32 byte random → ceil(32/3*4) = 43 chars,
+    // padding stripped. Erlaubt: A-Z a-z 0-9 - _
+    expect(plain).toMatch(/^[A-Za-z0-9_-]{43}$/);
+
+    // SHA256 hex = 64 chars
+    expect(hash).toMatch(/^[a-f0-9]{64}$/);
+
+    // Hash matched plain
+    const verifiedHash = await hashDownloadToken(plain);
+    expect(verifiedHash).toBe(hash);
+  });
+
+  test("zwei aufeinanderfolgende calls liefern unterschiedliche tokens (kryptographisch random)", async () => {
+    const t1 = await generateDownloadToken();
+    const t2 = await generateDownloadToken();
+    expect(t1.plain).not.toBe(t2.plain);
+    expect(t1.hash).not.toBe(t2.hash);
+  });
+
+  test("Token URL-safe (kein +/= im base64url)", async () => {
+    // Probabilistisch: 20× generieren + verifizieren dass keiner unsafe-chars hat.
+    // Pin gegen reine btoa-Verwendung (die liefert + / =).
+    for (let i = 0; i < 20; i++) {
+      const { plain } = await generateDownloadToken();
+      expect(plain).not.toMatch(/[+/=]/);
+    }
+  });
+});
+
+describe("hashDownloadToken", () => {
+  test("deterministic — selbe input → selbe hash", async () => {
+    const plain = "abc-123_test_token";
+    const h1 = await hashDownloadToken(plain);
+    const h2 = await hashDownloadToken(plain);
+    expect(h1).toBe(h2);
+  });
+
+  test("verschiedene inputs → verschiedene hashes", async () => {
+    const h1 = await hashDownloadToken("token-A");
+    const h2 = await hashDownloadToken("token-B");
+    expect(h1).not.toBe(h2);
+  });
+
+  test("SHA256-shape: 64 hex chars", async () => {
+    const h = await hashDownloadToken("anything");
+    expect(h).toMatch(/^[a-f0-9]{64}$/);
+  });
+});

package/src/user-data-rights/__tests__/user-data-rights.integration.ts

@@ -0,0 +1,57 @@
+// Boot-Smoke-Test fuer user-data-rights (S2.U2).
+//
+// Pre-Commit-Checkliste-Item: Neues Feature → 5-Zeilen-Boot-Smoke-Test.
+// Faengt Drift an Schema-Definition oder Boot-Validation frueh.
+//
+// Tieferer Cross-Feature-Test (mit useExtension(EXT_USER_DATA, ...) +
+// Sprint-2-H1/H2-Hooks) kommt in S2.T1 (Cross-Data-Matrix).
+
+import { setupTestStack, type TestStack } from "@cosmicdrift/kumiko-framework/stack";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { createComplianceProfilesFeature } from "../../compliance-profiles";
+import { createDataRetentionFeature } from "../../data-retention";
+import { createUserFeature } from "../../user";
+import { createUserDataRightsFeature } from "../feature";
+
+let stack: TestStack;
+
+const userFeature = createUserFeature();
+const dataRetention = createDataRetentionFeature();
+const complianceProfiles = createComplianceProfilesFeature();
+const userDataRights = createUserDataRightsFeature();
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [userFeature, dataRetention, complianceProfiles, userDataRights],
+  });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("user-data-rights :: feature-definition smoke", () => {
+  test("Feature laedt clean (requires user + data-retention + compliance-profiles)", () => {
+    expect(stack).toBeDefined();
+    expect(userDataRights.name).toBe("user-data-rights");
+  });
+
+  test("EXT_USER_DATA-Extension ist registriert (andere Features koennen useExtension dranhaengen)", () => {
+    expect(userDataRights.registrarExtensions["userData"]).toBeDefined();
+  });
+
+  test("requires user + data-retention + compliance-profiles", () => {
+    const requires = userDataRights.requires;
+    expect(requires).toContain("user");
+    expect(requires).toContain("data-retention");
+    expect(requires).toContain("compliance-profiles");
+  });
+
+  test("usesApi compliance.forTenant fuer Grace-Period-Resolution", () => {
+    expect(userDataRights.usedApis.has("compliance.forTenant")).toBe(true);
+  });
+
+  test("usesApi retention.policyFor fuer blockDelete-Konsultation (S2.D3 wired)", () => {
+    expect(userDataRights.usedApis.has("retention.policyFor")).toBe(true);
+  });
+});

package/src/user-data-rights/__tests__/zip-path.test.ts

@@ -0,0 +1,119 @@
+// zip-path Unit-Tests (S2.U3 Atom 3c).
+//
+// Pinst die ZIP-Pfad-Sanitization gegen Path-Traversal + edge-cases.
+// Diese Logik ist load-bearing — wenn sie failt, kann ein User-uploaded
+// Filename mit "../" einen ZIP-Reader dazu bringen, ausserhalb des
+// Extract-Roots zu schreiben.
+
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { describe, expect, test } from "vitest";
+import { buildFileRefZipPath, sanitizeZipFilename } from "../zip-path";
+
+const TENANT = "00000000-0000-0000-0000-000000000001" as TenantId;
+
+describe("sanitizeZipFilename", () => {
+  test("preserves alphanumeric + dot + dash + underscore", () => {
+    expect(sanitizeZipFilename("report-2024.pdf")).toBe("report-2024.pdf");
+    expect(sanitizeZipFilename("my_file.txt")).toBe("my_file.txt");
+    expect(sanitizeZipFilename("CamelCase-File_v2.docx")).toBe("CamelCase-File_v2.docx");
+  });
+
+  test("Path-Traversal: '../' → kein '..' im Output", () => {
+    // Klassisch: User uploaded "../../etc/passwd" als fileName. Reader
+    // wuerde sonst beim Extract aus dem ZIP-Root rausschreiben. Sanitize
+    // collaps `..`-Sequenzen + strippt leading dots/dashes/underscores.
+    // Resultat ist NICHT visually identical mit dem Original (informativ),
+    // aber garantiert kein '..'-Segment im final-Path.
+    const result = sanitizeZipFilename("../../etc/passwd");
+    expect(result).not.toContain("..");
+    expect(result).toBe("file.etc_passwd"); // Pfade kollabieren auf fallback-base + safe-ext
+
+    // Pure ".." faellt komplett auf fallback "file" zurueck.
+    expect(sanitizeZipFilename("..")).toBe("file");
+    expect(sanitizeZipFilename("...")).toBe("file");
+  });
+
+  test("Null-Byte: 'report\\x00.pdf' → 'report.pdf'", () => {
+    // Null-byte injection ist eine alte aber realistische Falle —
+    // Some C-based tools truncieren bei \x00, ZIP-Readern unklar.
+    expect(sanitizeZipFilename("report\x00.pdf")).toBe("report_.pdf");
+  });
+
+  test("Path-Separator: 'sub/dir/file.txt' → 'sub_dir_file.txt'", () => {
+    expect(sanitizeZipFilename("sub/dir/file.txt")).toBe("sub_dir_file.txt");
+    expect(sanitizeZipFilename("c:\\Users\\file")).toBe("c__Users_file");
+  });
+
+  test("Empty / null / undefined → 'unnamed'", () => {
+    expect(sanitizeZipFilename("")).toBe("unnamed");
+    // @ts-expect-error: null/undefined explicit defended
+    expect(sanitizeZipFilename(null)).toBe("unnamed");
+    // @ts-expect-error: null/undefined explicit defended
+    expect(sanitizeZipFilename(undefined)).toBe("unnamed");
+  });
+
+  test("All-special-chars (no remainder) → 'file' fallback", () => {
+    expect(sanitizeZipFilename("///")).toBe("file");
+    expect(sanitizeZipFilename("\\")).toBe("file");
+  });
+
+  test("Long basename gekappt (Extension preserved)", () => {
+    const longName = "a".repeat(200);
+    const result = sanitizeZipFilename(`${longName}.pdf`);
+    expect(result.length).toBeLessThanOrEqual(120);
+    expect(result.endsWith(".pdf")).toBe(true);
+  });
+
+  test("Long extension gekappt", () => {
+    const longExt = "x".repeat(50);
+    const result = sanitizeZipFilename(`file.${longExt}`);
+    expect(result.startsWith("file.")).toBe(true);
+    // Extension wird auf 20 chars max gekappt
+    const ext = result.split(".").pop() ?? "";
+    expect(ext.length).toBeLessThanOrEqual(20);
+  });
+
+  test("Hidden-File (leading dot) verliert leading-dot durch strip", () => {
+    // ".bashrc" — kein basename (lastDot=0 nicht "hasExt"-Bedingung).
+    // Wird also als raw-baseName behandelt + dann leading-dot gestrippt.
+    expect(sanitizeZipFilename(".bashrc")).toBe("bashrc");
+  });
+
+  test("Unicode chars (non-ASCII) werden zu underscore + ggf. fallback", () => {
+    // "résumé" basename: "r_sum_" → keine leading-strip, bleibt
+    // — aber: leading underscore wird gestrippt? Nein, nur leading "_._-"
+    // werden gestrippt vor strict basename. "r_sum_" startet mit "r".
+    expect(sanitizeZipFilename("résumé.pdf")).toBe("r_sum_.pdf");
+    // "文件" basename: "__" → all-underscore — kein strip aktiv weil
+    // erstes Zeichen ist "_" das in [._-] ist, also wird gestrippt
+    // → empty → fallback "file".
+    expect(sanitizeZipFilename("文件.txt")).toBe("file.txt");
+  });
+});
+
+describe("buildFileRefZipPath", () => {
+  test("Standard-Layout: files/<tenantId>/<fileRefId>-<name>", () => {
+    const path = buildFileRefZipPath({
+      tenantId: TENANT,
+      fileRefId: "abc-123",
+      fileName: "report.pdf",
+    });
+    expect(path).toBe(`files/${TENANT}/abc-123-report.pdf`);
+  });
+
+  test("Path-Traversal im fileName wird sanitized (kein '..' im Final-Path)", () => {
+    const path = buildFileRefZipPath({
+      tenantId: TENANT,
+      fileRefId: "abc",
+      fileName: "../../etc/passwd",
+    });
+    expect(path).toBe(`files/${TENANT}/abc-file.etc_passwd`);
+    expect(path).not.toContain("..");
+    expect(path.split("/").length).toBe(3); // exakt 3 segments: files / tenantId / sanitized-basename
+  });
+
+  test("Path ist deterministic — gleicher Input → gleicher Output", () => {
+    const args = { tenantId: TENANT, fileRefId: "x", fileName: "y.txt" };
+    expect(buildFileRefZipPath(args)).toBe(buildFileRefZipPath(args));
+  });
+});

package/src/user-data-rights/audit-download.ts

@@ -0,0 +1,125 @@
+// Audit-Helper fuer Download-Endpoint (S2.U3 Atom 4b).
+//
+// Beim Download (Token-Pfad oder Job-Pfad) werden Audit-Felder am
+// Token-Row aktualisiert:
+//   - useCount + 1
+//   - lastUsedAt = now
+//   - lastUsedFromIp = caller-IP (X-Forwarded-For oder Connection-IP)
+//   - lastUsedUserAgent = UA-Header
+//
+// **Best-Effort-Update:** version-conflicts (zwei parallel-Downloads
+// raceen um den update) werden silent geswallowt — Audit ist "letzter
+// Use", nicht "alle Uses". Der zweite Download succeeded trotzdem
+// (kein download-block bei race).
+//
+// **ES via tokenCrud.update:** kein direct-UPDATE. Memory
+// `feedback_no_fake_dispatcher` + `feedback_event_store_tenant_consistency`.
+
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { createSystemUser, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import { tokenCrud } from "./run-export-jobs";
+import { downloadAttemptEntity, downloadAttemptsTable } from "./schema/download-attempt";
+
+const attemptCrud = createEventStoreExecutor(downloadAttemptsTable, downloadAttemptEntity, {
+  entityName: "download-attempt",
+});
+
+type Instant = InstanceType<ReturnType<typeof getTemporal>["Instant"]>;
+
+export interface RecordDownloadUseArgs {
+  readonly db: DbConnection;
+  readonly tokenId: string;
+  readonly tokenVersion: number;
+  readonly tokenUseCount: number;
+  /**
+   * Tenant fuer die system-mode-TenantDb. ExportDownloadToken ist
+   * tenant-agnostisch (1:1 zum tenant-agnostic Job), aber der event-
+   * store-Stream-Lookup braucht einen Tenant-Context. Wir nutzen
+   * job.requestedFromTenantId — dieselbe Identitaet wie beim
+   * Token-Create im Worker (Atom 4a).
+   */
+  readonly tenantId: TenantId;
+  readonly now: Instant;
+  readonly ip: string | null;
+  readonly userAgent: string | null;
+}
+
+/**
+ * Audit-Update: useCount, lastUsedAt, IP, UA. Best-effort —
+ * version-conflicts (parallel-downloads) werden swallowed, Download
+ * succeeded trotzdem.
+ */
+export async function recordDownloadUse(args: RecordDownloadUseArgs): Promise<void> {
+  const { db, tokenId, tokenVersion, tokenUseCount, tenantId, now, ip, userAgent } = args;
+  const executor = createSystemUser(tenantId);
+  const tdb = createTenantDb(db, tenantId, "system");
+
+  await tokenCrud
+    .update(
+      {
+        id: tokenId,
+        version: tokenVersion,
+        changes: {
+          useCount: tokenUseCount + 1,
+          lastUsedAt: now,
+          lastUsedFromIp: ip,
+          lastUsedUserAgent: userAgent,
+        },
+      },
+      executor,
+      tdb,
+    )
+    .catch(() => {
+      // version-conflict bei parallelen Downloads → der erste hat
+      // bereits useCount inkrementiert. Wir behalten den Audit-Eintrag
+      // des ersten Downloads (lastUsedAt etc.). Kein download-block.
+    });
+}
+
+// extractCallerIp lebt in feature.ts (extractAuditMeta) — query-handler
+// haben keinen direkten Header-Zugriff (transport-agnostic), httpRoute-
+// Wrapper extrahiert + steckt in payload.auditMeta.
+
+export type DownloadAttemptResult = "notFound" | "expired" | "failed" | "signedUrlNotSupported";
+
+export interface RecordInvalidAttemptArgs {
+  readonly db: DbConnection;
+  readonly tenantId: TenantId;
+  readonly now: Instant;
+  readonly result: DownloadAttemptResult;
+  readonly via: "token" | "job";
+  readonly tokenHash: string | null;
+  readonly jobId: string | null;
+  readonly attemptedByUserId: string | null;
+  readonly ip: string | null;
+  readonly userAgent: string | null;
+}
+
+// Best-effort INSERT in read_download_attempts. Throws im Audit-Pfad
+// duerfen den Download-Endpoint nicht killen (User soll seinen 404
+// bekommen, nicht 500); failures werden silent geswallowt.
+export async function recordInvalidAttempt(args: RecordInvalidAttemptArgs): Promise<void> {
+  const { db, tenantId, now } = args;
+  const executor = createSystemUser(tenantId);
+  const tdb = createTenantDb(db, tenantId, "system");
+  await attemptCrud
+    .create(
+      {
+        result: args.result,
+        via: args.via,
+        tokenHash: args.tokenHash,
+        jobId: args.jobId,
+        attemptedByUserId: args.attemptedByUserId,
+        ip: args.ip,
+        userAgent: args.userAgent,
+        attemptedAt: now,
+      },
+      executor,
+      tdb,
+    )
+    .catch(() => {
+      // best-effort
+    });
+}