@cosmicdrift/kumiko-samples 0.338.0

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

@@ -0,0 +1,259 @@
+// GET /api/query → user-data-rights:query:download-by-token (S2.U3 Atom 4b).
+//
+// **Magic-Link-Pfad** (anonymous): User klickt Email-Link mit
+// `#token=<plain>` (URL fragment, issue #1271). Worker hat beim done-flip Token-Hash in DB
+// persistiert (Atom 4a). Verify-Pipeline:
+//
+//   1. hashDownloadToken(plain) → fetchOne in download-tokens
+//   2. expiresAt > now (Multi-use within TTL — Plan-Decision)
+//   3. job.status === "done"
+//   4. job.downloadStorageKey != null (storage nicht gecleared)
+//   5. provider.getSignedUrl pflicht (501 wenn Provider local-fs ist)
+//   6. Audit-Update: useCount + 1, lastUsedAt, IP, UA (best-effort, race-tolerant)
+//   7. Return {url, expiresAt}
+//
+// **Sicherheit:**
+//   - Token-Hash-Compare via DB-fetchOne (nicht constant-time, aber
+//     timing-attacks auf SHA256-bytes brauchen >>10k requests + stable
+//     latenz — in Web-App-Kontext nicht ausnutzbar). Plan-Decision: harden
+//     wenn Pen-Test es flaggt.
+//   - 404 bei invalidem Token (kein Existenz-Leak) — gleicher Code-Pfad
+//     wie nicht-gefundenes Token.
+//   - tenant-agnostic: Token ist global eindeutig (UUID + SHA256), kein
+//     Tenant-Filter nötig.
+//
+// **r.httpRoute-Wrapper** (siehe feature.ts) macht 302-Redirect zu
+// signedUrl — User klickt 1× Email-Link, Browser folgt redirect, Download
+// startet. Dieser query-handler liefert nur das JSON.
+
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  defineQueryHandler,
+  SYSTEM_USER_ID,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { NotFoundError, UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import * as z from "zod";
+import { recordDownloadUse, recordInvalidAttempt } from "../audit-download.js";
+import { makeTenantStorageProviderResolver } from "../lib/storage-provider-resolver.js";
+import { exportDownloadTokensTable } from "../schema/download-token.js";
+import { EXPORT_JOB_STATUS, exportJobsTable } from "../schema/export-job.js";
+import { hashDownloadToken } from "../token-helpers.js";
+
+type Instant = InstanceType<ReturnType<typeof getTemporal>["Instant"]>;
+
+const SIGNED_URL_TTL_SECONDS = 300; // 5 min — kurz genug fuer Replay-Schutz, lang genug fuer slow connections
+
+const DOWNLOAD_BY_TOKEN_REASON =
+  "the download token, its job and audit rows are keyed by token hash / job id, not the caller's tenant — the anonymous magic-link path has no tenant context at all";
+
+interface TokenRow {
+  readonly id: string;
+  readonly version: number;
+  readonly jobId: string;
+  readonly expiresAt: Instant;
+  readonly useCount: number | null;
+}
+
+interface JobRow {
+  readonly id: string;
+  readonly userId: string;
+  readonly requestedFromTenantId: string;
+  readonly status: string;
+  readonly downloadStorageKey: string | null;
+  readonly bytesWritten: number | null;
+}
+
+export const downloadByTokenQuery = defineQueryHandler({
+  name: "download-by-token",
+  schema: z.object({
+    token: z.string().min(1, "token required"),
+    auditMeta: z
+      .object({
+        ip: z.string().nullable(),
+        userAgent: z.string().nullable(),
+      })
+      .optional(),
+  }),
+  access: { roles: ["anonymous", "Member", "User", "TenantAdmin", "SystemAdmin"] },
+  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
+  // defense-in-depth + Schutz gegen Storm-Patterns die DB-Last erzeugen.
+  // 30 attempts/min/IP reicht fuer legitime User (mehrere Klicks bei
+  // Connection-Abbruch); blockiert automatisierte Probing-Loops.
+  // Memory `feedback_security_default_on`.
+  rateLimit: { per: "ip+handler", limit: 30, windowSeconds: 60 },
+  escapeHatch: {
+    grants: ["unsafeRaw"],
+    reason: DOWNLOAD_BY_TOKEN_REASON,
+  },
+  handler: async (query, ctx) => {
+    const T = getTemporal();
+    const now = T.Now.instant();
+    const runner = ctx.db.unsafeRaw(DOWNLOAD_BY_TOKEN_REASON);
+
+    // Step 1: hash + lookup
+    const hash = await hashDownloadToken(query.payload.token);
+    const tokenRow = await fetchOne<TokenRow>(runner, exportDownloadTokensTable, {
+      tokenHash: hash,
+    });
+
+    if (!tokenRow) {
+      // Invalid token — 404 ohne Existenz-Leak. Generic NotFoundError
+      // damit alle Failure-Pfade die gleiche externe Shape haben (kein
+      // Probing zwischen "Token existiert nicht" vs "Job ist failed").
+      throw new NotFoundError("export-download", undefined, {
+        i18nKey: "userDataRights.errors.download.notFound",
+      });
+    }
+
+    const auditIp = query.payload.auditMeta?.ip ?? null;
+    const auditUa = query.payload.auditMeta?.userAgent ?? null;
+
+    // Step 2: TTL-check.
+    //
+    // **Pragma:** semantisch waere 410 Gone richtig (war mal da, jetzt
+    // nicht mehr). Framework hat keine GoneError-Class; wir nutzen
+    // NotFoundError + i18nKey "expired" als Kompromiss. UI rendert
+    // anhand des i18nKeys, nicht des HTTP-Status — also User sieht
+    // "Dein Download ist abgelaufen", nicht generic "not found".
+    if (tokenRow.expiresAt.epochMilliseconds <= now.epochMilliseconds) {
+      // Audit-Skip noch nicht moeglich — jobRow noch nicht geladen,
+      // tenantId unbekannt. Wir laden den Job hier noch fuer Audit-Context
+      // (best-effort — wenn Job auch fehlt, audit-skip ist akzeptabel).
+      const jobForAudit = await fetchOne<{ requestedFromTenantId: string }>(
+        runner,
+        exportJobsTable,
+        {
+          id: tokenRow.jobId,
+        },
+      );
+      if (jobForAudit) {
+        await recordInvalidAttempt({
+          db: runner,
+          tenantId: jobForAudit.requestedFromTenantId,
+          now,
+          result: "expired",
+          via: "token",
+          tokenHash: hash,
+          jobId: tokenRow.jobId,
+          attemptedByUserId: null,
+          ip: auditIp,
+          userAgent: auditUa,
+        });
+      }
+      throw new NotFoundError("export-download", undefined, {
+        i18nKey: "userDataRights.errors.download.expired",
+      });
+    }
+
+    // Step 3-4: job-checks
+    const jobRow = await fetchOne<JobRow>(runner, exportJobsTable, {
+      id: tokenRow.jobId,
+    });
+
+    if (!jobRow) {
+      throw new NotFoundError("export-download", undefined, {
+        i18nKey: "userDataRights.errors.download.notFound",
+      });
+    }
+    if (jobRow.status !== EXPORT_JOB_STATUS.Done) {
+      await recordInvalidAttempt({
+        db: runner,
+        tenantId: jobRow.requestedFromTenantId,
+        now,
+        result: "failed",
+        via: "token",
+        tokenHash: hash,
+        jobId: jobRow.id,
+        attemptedByUserId: null,
+        ip: auditIp,
+        userAgent: auditUa,
+      });
+      throw new NotFoundError("export-download", undefined, {
+        i18nKey: "userDataRights.errors.download.unavailable",
+      });
+    }
+    if (!jobRow.downloadStorageKey) {
+      await recordInvalidAttempt({
+        db: runner,
+        tenantId: jobRow.requestedFromTenantId,
+        now,
+        result: "expired",
+        via: "token",
+        tokenHash: hash,
+        jobId: jobRow.id,
+        attemptedByUserId: null,
+        ip: auditIp,
+        userAgent: auditUa,
+      });
+      throw new NotFoundError("export-download", undefined, {
+        i18nKey: "userDataRights.errors.download.expired",
+      });
+    }
+
+    // Step 5: signed-URL via provider, explicitly bound to the job's
+    // tenant — NOT the ambient request tenant (anonymous magic-link path
+    // has none under resolverTrust: "authoritative").
+    const provider = await makeTenantStorageProviderResolver({
+      registry: ctx.registry,
+      configResolver: ctx.configResolver,
+      secrets: ctx.secrets,
+      // @cast-boundary db-runner — helpers use only the query API that
+      // DbConnection and DbTx share.
+      db: runner as import("@cosmicdrift/kumiko-types/db-connection").DbConnection,
+      userId: SYSTEM_USER_ID,
+      handlerName: "user-data-rights:query:download-by-token",
+    })(jobRow.requestedFromTenantId as TenantId); // @cast-boundary engine-payload: TenantId brand
+    if (!provider.getSignedUrl) {
+      await recordInvalidAttempt({
+        db: runner,
+        tenantId: jobRow.requestedFromTenantId,
+        now,
+        result: "signedUrlNotSupported",
+        via: "token",
+        tokenHash: hash,
+        jobId: jobRow.id,
+        attemptedByUserId: null,
+        ip: auditIp,
+        userAgent: auditUa,
+      });
+      throw new UnprocessableError("storage_provider_signed_url_not_supported", {
+        i18nKey: "userDataRights.errors.download.signedUrlNotSupported",
+      });
+    }
+
+    const signedUrl = await provider.getSignedUrl(
+      jobRow.downloadStorageKey,
+      SIGNED_URL_TTL_SECONDS,
+      {
+        contentDisposition: `attachment; filename="user-data-export-${jobRow.id}.zip"`,
+      },
+    );
+    const signedUrlExpiresAt = T.Instant.fromEpochMilliseconds(
+      now.epochMilliseconds + SIGNED_URL_TTL_SECONDS * 1000,
+    );
+
+    // Step 6: Audit-Update best-effort. auditMeta kommt vom httpRoute-
+    // Wrapper (trusted-source). Direct-API-caller koennen luegen, aber
+    // Audit ist nicht security-relevant.
+    await recordDownloadUse({
+      db: runner,
+      tokenId: tokenRow.id,
+      tokenVersion: tokenRow.version,
+      tokenUseCount: tokenRow.useCount ?? 0,
+      tenantId: jobRow.requestedFromTenantId,
+      now,
+      ip: query.payload.auditMeta?.ip ?? null,
+      userAgent: query.payload.auditMeta?.userAgent ?? null,
+    });
+
+    return {
+      url: signedUrl,
+      expiresAt: signedUrlExpiresAt.toString(),
+      bytesWritten: jobRow.bytesWritten,
+    };
+  },
+});

package/packages/bundled-features/src/user-data-rights/handlers/export-job-detail.query.ts

@@ -0,0 +1,13 @@
+import { access, defineEntityDetailHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { exportJobEntity } from "../schema/export-job.js";
+
+// Detail fetch backing the read-only export-job inspector screen.
+export const exportJobDetailQuery = defineEntityDetailHandler("export-job", exportJobEntity, {
+  access: { roles: access.systemAdmin },
+  escapeHatch: {
+    reason:
+      "SystemAdmin GDPR Art. 20 export inspector opens one data-export job owned by any tenant for platform-operator support",
+  },
+  description:
+    "Read-only cross-tenant detail view of one GDPR data-export job for the system-admin inspector, showing its lifecycle timestamps, storage key, byte count and error message.",
+});

package/packages/bundled-features/src/user-data-rights/handlers/export-job-list.query.ts

@@ -0,0 +1,14 @@
+import { access, defineEntityListHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { exportJobEntity } from "../schema/export-job.js";
+
+// SystemAdmin operator view of GDPR Art. 20 export jobs. Read-only inspector —
+// rows are created by the user's request-export flow, never through this handler.
+export const exportJobListQuery = defineEntityListHandler("export-job", exportJobEntity, {
+  access: { roles: access.systemAdmin },
+  escapeHatch: {
+    reason:
+      "SystemAdmin GDPR Art. 20 export inspector lists data-export jobs of every tenant for platform-operator support",
+  },
+  description:
+    "Read-only cross-tenant list of GDPR Art. 20 data-export jobs for the system-admin inspector; use export-status instead when a user asks about their own export.",
+});

package/packages/bundled-features/src/user-data-rights/handlers/export-status.query.ts

@@ -0,0 +1,75 @@
+// GET /api/user/export-status (S2.U3 Atom 2) — User-Polling.
+//
+// Liefert den meist-aktuellen ExportJob des aufrufenden Users (in
+// Reihenfolge: aktiver Job zuerst, sonst neuester done/failed).
+//
+// **Cross-User-Isolation:** Filter ist `userId === query.user.id` — kein
+// User kann fremde Job-Status sehen, auch nicht via ID-Guess. Pre-Check
+// uses ctx.db.unsafeRaw — ExportJob is tenant-agnostic (see plan doc,
+// "Cross-Tenant-Semantik").
+//
+// **Read-Only-Endpoint:** Pollt nur, kein State-Flip. Idempotent + cache-
+// fest. UI poll-Intervall typisch 2-5s waehrend running.
+
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import type { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import * as z from "zod";
+import { exportJobsTable } from "../schema/export-job.js";
+
+type Instant = InstanceType<ReturnType<typeof getTemporal>["Instant"]>;
+
+const EXPORT_STATUS_REASON =
+  "export jobs are keyed by userId across all of the user's tenant memberships, not the caller's current tenant";
+
+type ExportJobRow = {
+  readonly id: string;
+  readonly status: string;
+  readonly requestedAt: Instant;
+  readonly completedAt: Instant | null;
+  readonly expiresAt: Instant | null;
+  readonly errorMessage: string | null;
+  readonly bytesWritten: number | null;
+};
+
+export const exportStatusQuery = defineQueryHandler({
+  name: "export-status",
+  schema: z.object({}),
+  access: {
+    openToAll: {
+      reason:
+        "each signed-in user reads only their own most recent export job; the query " +
+        "filters exportJobsTable by the caller's own userId",
+    },
+  },
+  description:
+    "Returns the calling user's own most recent data-export job with its status, expiry and error, or hasJob false, for polling after a request-export while the job is still running.",
+  escapeHatch: {
+    grants: ["unsafeRaw"],
+    reason: EXPORT_STATUS_REASON,
+  },
+  handler: async (query, ctx) => {
+    const rows = await selectMany<ExportJobRow>(
+      ctx.db.unsafeRaw(EXPORT_STATUS_REASON),
+      exportJobsTable,
+      { userId: query.user.id },
+      { limit: 1, orderBy: { col: "requestedAt", direction: "desc" } },
+    );
+
+    const latest = rows[0];
+    if (!latest) return { hasJob: false as const };
+
+    return {
+      hasJob: true as const,
+      job: {
+        id: latest.id,
+        status: latest.status,
+        requestedAt: latest.requestedAt.toString(),
+        completedAt: latest.completedAt?.toString() ?? null,
+        expiresAt: latest.expiresAt?.toString() ?? null,
+        errorMessage: latest.errorMessage,
+        bytesWritten: latest.bytesWritten,
+      },
+    };
+  },
+});

package/packages/bundled-features/src/user-data-rights/handlers/lift-restriction.write.ts

@@ -0,0 +1,88 @@
+import { access, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { USER_STATUS, userTable } from "../../user/index.js";
+import { denyIfTargetOutsideAdminTenant } from "../lib/deny-if-target-outside-admin-tenant.js";
+import { updateUserLifecycle } from "../lib/update-user-lifecycle.js";
+
+const LIFT_RESTRICTION_ESCAPE_HATCH_REASON =
+  "checks the target user's membership in the admin's tenant and appends the user lifecycle status change on the SYSTEM_TENANT_ID user stream, both via DbRunner helpers outside the admin's own tenant scope.";
+const CHECK_TARGET_MEMBERSHIP_REASON =
+  "checks the target user's membership in the admin's tenant via the DbRunner helper";
+const APPEND_LIFECYCLE_EVENT_REASON =
+  "appends the user lifecycle event on the SYSTEM_TENANT_ID user stream";
+
+// POST /api/user/lift-restriction (S2.U6) — DSGVO Art. 18 Reverse.
+//
+// Operator-only. A Restricted user's own session is unconditionally
+// rejected by sessionChecker (BLOCKED_STATUSES) the moment their status
+// flips — their JWT/login can't reach this or any other authenticated
+// endpoint. There is no self-service path today, so lifting a restriction
+// always targets someone else's account by id.
+//
+// Tenant scope: `access.admin` includes TenantAdmin (tenant-scoped) even
+// though the User-entity is global — see user-data-rights.md "Cross-Tenant-Semantik". Without a membership check, a TenantAdmin
+// from tenant A could unrestrict/reactivate a user who has never been a
+// member of tenant A. Only SystemAdmin (platform-wide) skips the check;
+// the target must have a membership row in the acting admin's
+// `event.user.tenantId` (row existence only — no active-status field).
+//
+// State-Transitions:
+//   Restricted → Active        ✓
+//   Active → ...               ✗ 422 not_restricted (Idempotenz-Guard)
+//   DeletionRequested → ...    ✗ 422 not_restricted
+//   Deleted → ...              ✗ 422 not_restricted
+export const liftRestrictionWrite = defineWriteHandler({
+  name: "lift-restriction",
+  schema: z.object({ userId: z.string().uuid() }),
+  access: { roles: access.admin },
+  description:
+    "Lifts a GDPR Art. 18 processing restriction on the named user and returns the account to active; operator-only, because a restricted user's own session is rejected and cannot reach this endpoint.",
+  escapeHatch: {
+    grants: ["unsafeRaw", "globalWrites"],
+    reason: LIFT_RESTRICTION_ESCAPE_HATCH_REASON,
+  },
+  handler: async (event, ctx) => {
+    const targetUserId = event.payload.userId;
+
+    const outside = await denyIfTargetOutsideAdminTenant(
+      ctx.db.unsafeRaw(CHECK_TARGET_MEMBERSHIP_REASON),
+      event.user,
+      targetUserId,
+    );
+    if (outside) return outside;
+
+    const userRow = await ctx.db.global(userTable).fetchOne<{ status: string }>({
+      id: targetUserId,
+    });
+
+    if (!userRow) {
+      return writeFailure(
+        new UnprocessableError("user_not_found", {
+          details: { userId: targetUserId },
+        }),
+      );
+    }
+
+    const currentStatus = userRow["status"];
+    if (currentStatus !== USER_STATUS.Restricted) {
+      return writeFailure(
+        new UnprocessableError("not_restricted", {
+          details: { currentStatus },
+        }),
+      );
+    }
+
+    await updateUserLifecycle(ctx.db.unsafeRaw(APPEND_LIFECYCLE_EVENT_REASON), targetUserId, {
+      status: USER_STATUS.Active,
+    });
+
+    return {
+      isSuccess: true as const,
+      data: {
+        userId: targetUserId,
+        status: USER_STATUS.Active,
+      },
+    };
+  },
+});

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

@@ -0,0 +1,49 @@
+import { selectMany, type WhereObject } from "@cosmicdrift/kumiko-framework/bun-db";
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { Temporal } from "temporal-polyfill";
+import * as z from "zod";
+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;
+
+export const listDownloadAttemptsQuery = defineQueryHandler({
+  name: "list-download-attempts",
+  schema: z
+    .object({
+      limit: z.number().int().min(1).max(MAX_LIMIT).default(50),
+      result: z.enum(["notFound", "expired", "failed", "signedUrlNotSupported"]).optional(),
+      ip: z.string().optional(),
+      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`",
+    }),
+  access: { roles: ["Admin", "SystemAdmin"] },
+  description:
+    "Lists invalid export-download attempts inside the caller's own tenant, filterable by failure result, source IP and time range, for a data protection officer triaging brute-force probing of download links.",
+  // Source IPs of the probing attempts.
+  agent: { risk: "high" },
+  handler: async (query, ctx) => {
+    const p = query.payload;
+    const where: WhereObject = { tenantId: query.user.tenantId };
+    if (p.result) where["result"] = p.result;
+    if (p.ip) where["ip"] = p.ip;
+    if (p.from || p.to) {
+      const range: { gte?: unknown; lte?: unknown } = {};
+      if (p.from) range.gte = Temporal.Instant.from(p.from);
+      if (p.to) range.lte = Temporal.Instant.from(p.to);
+      where["attemptedAt"] = range;
+    }
+
+    const rows = await selectMany(ctx.db, downloadAttemptsTable, where, {
+      orderBy: { col: "attemptedAt", direction: "desc" },
+      limit: p.limit,
+    });
+
+    return { rows };
+  },
+});

package/packages/bundled-features/src/user-data-rights/handlers/my-audit-log.query.ts

@@ -0,0 +1,87 @@
+import { selectMany, type WhereObject } from "@cosmicdrift/kumiko-framework/bun-db";
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import { Temporal } from "temporal-polyfill";
+import * as z from "zod";
+
+// DSGVO Art. 15 Selbstauskunft — User reads HIS OWN audit-log.
+// WHERE createdBy = ctx.user.id ist hard-coded (kein userId-Param,
+// anti-cross-user-Snooping). KEIN tenantId-Filter: User hat Anspruch
+// auf account-weite Sicht ueber alle Memberships — analog Forget-Pfad.
+const MAX_LIMIT = 100;
+
+const MY_AUDIT_LOG_REASON =
+  "reads the caller's own events across all tenant memberships, bounded by createdBy = caller";
+
+export const myAuditLogQuery = defineQueryHandler({
+  name: "my-audit-log",
+  schema: z
+    .object({
+      before: z.string().regex(/^\d+$/, "cursor must be a positive integer").optional(),
+      limit: z.number().int().min(1).max(MAX_LIMIT).default(50),
+      aggregateType: z.string().optional(),
+      eventType: z.string().optional(),
+      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: {
+    openToAll: {
+      reason:
+        "each signed-in user reads only their own event-store history for the GDPR " +
+        "Art. 15 self-disclosure; the query hard-codes createdBy = caller and can never " +
+        "read another user's history",
+    },
+  },
+  description:
+    "Returns the calling user's own event-store entries across all their tenant memberships, paged and filterable by aggregate type, event type and time range, for the GDPR Art. 15 self-disclosure; it can never read another user's history.",
+  escapeHatch: {
+    grants: ["unsafeRaw"],
+    reason: MY_AUDIT_LOG_REASON,
+  },
+  handler: async (query, ctx) => {
+    const p = query.payload;
+
+    const where: WhereObject = { createdBy: query.user.id };
+    if (p.aggregateType) where["aggregateType"] = p.aggregateType;
+    if (p.eventType) where["type"] = p.eventType;
+    if (p.from || p.to) {
+      const range: { gte?: unknown; lte?: unknown } = {};
+      if (p.from) range.gte = Temporal.Instant.from(p.from);
+      if (p.to) range.lte = Temporal.Instant.from(p.to);
+      where["createdAt"] = range;
+    }
+    if (p.before) where["id"] = { lt: BigInt(p.before) };
+
+    const rows = await selectMany<{
+      id: bigint;
+      aggregate_id: string;
+      aggregate_type: string;
+      version: number;
+      type: string;
+      payload: Record<string, unknown>;
+      created_at: unknown;
+    }>(ctx.db.unsafeRaw(MY_AUDIT_LOG_REASON), eventsTable, where, {
+      orderBy: { col: "id", direction: "desc" },
+      limit: p.limit,
+    });
+
+    const serialised = rows.map((r) => ({
+      id: String(r["id"]),
+      aggregateId: r["aggregate_id"],
+      aggregateType: r["aggregate_type"],
+      version: r["version"],
+      type: r["type"],
+      payload: r["payload"],
+      createdAt: r["created_at"],
+    }));
+    const last = serialised[serialised.length - 1];
+    return {
+      rows: serialised,
+      nextBefore: serialised.length === p.limit && last ? last["id"] : null,
+    };
+  },
+});